@octane-xplat/camera 0.13.0 → 0.14.0

package/dist/web/session-core.js

@@ -0,0 +1,368 @@
+import { CameraCaptureError } from "./types.js";
+//#region src/session-core.ts
+var attemptCounter = 0;
+var issue = (kind, operation, message, extra) => new CameraCaptureError({
+	kind,
+	operation,
+	message,
+	...extra
+});
+/** The concrete session object wrapping a platform backend. Internal to
+*  the package; `CameraSession` is the public shape. */
+var SharedCameraSession = class {
+	backend;
+	config;
+	listeners = /* @__PURE__ */ new Set();
+	state = "idle";
+	permission = {
+		camera: "unknown",
+		microphone: "unknown"
+	};
+	cameraAvailable = true;
+	previewAttached = false;
+	interrupted = false;
+	disposeRequested = false;
+	disposed = false;
+	lastCapabilities;
+	requestChains = /* @__PURE__ */ new Map();
+	attempt;
+	constructor(backend, config) {
+		this.backend = backend;
+		this.config = { ...config };
+		backend.setObserver({
+			interruption: (phase, reason) => this.handleInterruption(phase, reason),
+			availability: (available) => this.handleAvailability(available),
+			previewReady: () => {
+				this.emit({
+					type: "stateChanged",
+					snapshot: this.snapshot()
+				});
+			}
+		});
+	}
+	/** Package-internal: attach a preview host to this session. */
+	attach(host, listener) {
+		if (this.disposed || this.disposeRequested) throw issue("invalidState", "attachPreview", "CameraSession is disposed");
+		if (this.previewAttached) throw issue("invalidState", "attachPreview", "CameraSession already has a preview");
+		const detach = this.backend.attachPreview(host, {
+			onReady: listener?.onReady,
+			onError: (captureIssue) => {
+				listener?.onError?.(captureIssue);
+			}
+		});
+		this.previewAttached = true;
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+		return () => {
+			this.detachInternal(detach);
+		};
+	}
+	get attached() {
+		return this.previewAttached;
+	}
+	detachInternal(detach) {
+		if (!this.previewAttached) return;
+		this.previewAttached = false;
+		const attempt = this.attempt;
+		if (attempt && (attempt.state === "starting" || attempt.state === "recording")) this.requestStop("previewReleased");
+		detach();
+		this.backend.onPreviewDetached?.();
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+	}
+	emit(event) {
+		for (const listener of this.listeners) try {
+			listener(event);
+		} catch {}
+	}
+	setState(state) {
+		if (this.state === state) return;
+		this.state = state;
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+	}
+	snapshot() {
+		const attempt = this.attempt;
+		return {
+			state: this.state,
+			permission: { ...this.permission },
+			cameraAvailable: this.cameraAvailable,
+			previewAttached: this.previewAttached,
+			interrupted: this.interrupted,
+			attempt: attempt && attempt.state !== "settled" ? {
+				id: attempt.id,
+				state: attempt.state,
+				elapsedMs: this.backend.elapsedMs(),
+				configuration: attempt.configuration
+			} : void 0
+		};
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	async permissions() {
+		const [camera, microphone] = await Promise.all([this.backend.checkPermission("camera"), this.backend.checkPermission("microphone")]);
+		this.permission = {
+			camera,
+			microphone
+		};
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+		return { ...this.permission };
+	}
+	requestPermission(kind) {
+		const chain = (this.requestChains.get(kind) ?? Promise.resolve("unknown")).then(async () => {
+			if (this.disposed) return this.permission[kind];
+			const status = await this.backend.requestPermission(kind);
+			this.permission = {
+				...this.permission,
+				[kind]: status
+			};
+			this.emit({
+				type: "stateChanged",
+				snapshot: this.snapshot()
+			});
+			return status;
+		});
+		this.requestChains.set(kind, chain);
+		return chain;
+	}
+	async capabilities() {
+		const capabilities = await this.backend.getCapabilities();
+		this.lastCapabilities = capabilities;
+		return capabilities;
+	}
+	async configure(next) {
+		if (this.disposed || this.disposeRequested) throw issue("invalidState", "configure", "CameraSession is disposed");
+		if (this.state !== "idle") throw issue("invalidState", "configure", `CameraSession cannot configure while ${this.state}`);
+		const merged = {
+			...this.config,
+			...next
+		};
+		const capabilities = await this.capabilities();
+		this.validateCameraSelection(merged.camera, capabilities);
+		this.config = merged;
+		this.backend.configure?.(merged);
+	}
+	validateCameraSelection(camera, capabilities) {
+		if (camera && typeof camera === "object" && "deviceId" in camera) {
+			if (!capabilities.cameras.some((entry) => entry.id === camera.deviceId)) throw issue("unsupportedConfiguration", "configure", `Camera device '${camera.deviceId}' is not available`);
+		} else if (camera === "front" || camera === "back") {
+			if (!capabilities.cameras.some((entry) => entry.facing === camera) && capabilities.cameras.length > 0) throw issue("unsupportedConfiguration", "configure", `No ${camera}-facing camera is available`);
+		}
+	}
+	requestStop(cause) {
+		const attempt = this.attempt;
+		if (!attempt || attempt.state === "finalizing" || attempt.state === "settled") return;
+		attempt.stopRequested = true;
+		attempt.cause ??= cause;
+		if (attempt.state === "recording") {
+			this.setState("finalizing");
+			attempt.state = "finalizing";
+			try {
+				this.backend.stopCapture();
+			} catch {}
+		}
+	}
+	handleInterruption(phase, reason) {
+		this.interrupted = phase === "began";
+		this.emit({
+			type: "interruption",
+			phase,
+			reason
+		});
+		if (phase === "began") {
+			const cause = reason === "background" ? "backgrounded" : reason === "cameraInUse" ? "cameraUnavailable" : "interrupted";
+			this.requestStop(cause);
+		}
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+	}
+	handleAvailability(available) {
+		if (this.cameraAvailable === available) return;
+		this.cameraAvailable = available;
+		this.emit({
+			type: "availability",
+			available
+		});
+		if (!available) this.requestStop("cameraUnavailable");
+		this.emit({
+			type: "stateChanged",
+			snapshot: this.snapshot()
+		});
+	}
+	startRecording(options = {}) {
+		const operation = "startRecording";
+		if (this.disposed || this.disposeRequested) throw issue("invalidState", operation, "CameraSession is disposed");
+		if (!this.backend.supported) throw issue("unsupportedPlatform", operation, "Movie recording is unsupported on this platform");
+		if (this.state !== "idle" || this.attempt) throw issue("busy", operation, `CameraSession is ${this.state}`);
+		if (options.maximumDurationMs !== void 0) {
+			const value = options.maximumDurationMs;
+			if (!Number.isFinite(value) || value <= 0) throw issue("invalidArgument", operation, "maximumDurationMs must be a positive finite number of milliseconds");
+		}
+		if (options.destinationFileUrl !== void 0 && !options.destinationFileUrl.startsWith("file://")) throw issue("invalidArgument", operation, "destinationFileUrl must be a local file:// URL");
+		if (options.orientation !== void 0 && options.orientation !== "unspecified" && this.lastCapabilities && !this.lastCapabilities.orientations.includes(options.orientation)) throw issue("unsupportedConfiguration", "startRecording", `Orientation '${options.orientation}' is not advertised by this camera`);
+		if (this.interrupted || !this.cameraAvailable || !this.backend.previewReady()) throw issue("unavailable", operation, this.interrupted ? "Camera session is interrupted" : !this.cameraAvailable ? "Camera is unavailable" : "An active, ready preview is required before recording");
+		this.backend.validateStart?.(options);
+		attemptCounter += 1;
+		const id = `take-${Date.now()}-${attemptCounter}`;
+		let resolveCompletion;
+		const completion = new Promise((resolve) => {
+			resolveCompletion = resolve;
+		});
+		const attempt = {
+			id,
+			state: "starting",
+			stopRequested: false,
+			resolve: resolveCompletion,
+			completion
+		};
+		this.attempt = attempt;
+		this.setState("starting");
+		const capabilities = this.lastCapabilities;
+		const sink = {
+			started: (configuration) => {
+				const current = this.attempt;
+				if (!current || current.id !== id || current.state === "settled") return;
+				current.configuration = configuration;
+				current.startedAt = Date.now();
+				if (current.state === "starting") {
+					current.state = "recording";
+					this.setState("recording");
+					this.emit({
+						type: "started",
+						attemptId: id,
+						configuration
+					});
+					if (options.maximumDurationMs !== void 0 && capabilities?.durationLimit === "bestEffort") {
+						const limit = options.maximumDurationMs;
+						const checkLimit = () => {
+							if (this.attempt?.id !== id || current.state !== "recording") return;
+							const remaining = limit - this.backend.elapsedMs();
+							if (remaining > 0) current.limitTimer = setTimeout(checkLimit, Math.min(remaining, 2147483647));
+							else this.requestStop("maximumDuration");
+						};
+						current.limitTimer = setTimeout(checkLimit, Math.min(limit, 2147483647));
+					}
+					if (current.stopRequested) this.requestStop(current.cause ?? "stopped");
+				}
+			},
+			finishing: (reason) => {
+				const current = this.attempt;
+				if (!current || current.id !== id || current.state === "settled") return;
+				current.cause ??= reason;
+				current.state = "finalizing";
+				this.setState("finalizing");
+			},
+			settled: (result) => {
+				const current = this.attempt;
+				if (!current || current.id !== id || current.state === "settled") return;
+				if (current.limitTimer) clearTimeout(current.limitTimer);
+				current.state = "settled";
+				const cause = current.cause ?? (result.kind === "clip" ? result.endReason : void 0);
+				const outcome = result.kind === "clip" ? {
+					kind: "clip",
+					clip: {
+						output: result.output,
+						mimeType: result.mimeType,
+						durationMs: result.durationMs,
+						width: result.width,
+						height: result.height,
+						orientation: result.orientation,
+						hasAudio: result.hasAudio
+					},
+					endReason: cause ?? (result.limitReached ? "maximumDuration" : "stopped"),
+					partial: cause !== void 0 && cause !== "stopped" && cause !== "maximumDuration",
+					warning: result.warning
+				} : {
+					kind: "failed",
+					endReason: cause ?? "captureError",
+					stage: result.stage,
+					error: new CameraCaptureError(result.issue)
+				};
+				this.attempt = void 0;
+				current.resolve(outcome);
+				this.emit({
+					type: "finished",
+					attemptId: id,
+					outcome
+				});
+				if (this.disposeRequested) this.finishDispose();
+				else this.setState("idle");
+			}
+		};
+		const request = {
+			audio: this.config.audio === true,
+			orientation: options.orientation,
+			maximumDurationMs: options.maximumDurationMs,
+			destinationPath: options.destinationFileUrl?.startsWith("file://") ? decodeURIComponent(options.destinationFileUrl.slice(7)) : void 0
+		};
+		try {
+			this.backend.startCapture(request, sink);
+		} catch (cause) {
+			sink.settled({
+				kind: "failed",
+				stage: "preparation",
+				issue: cause instanceof CameraCaptureError ? cause : {
+					kind: "captureFailed",
+					operation: "startRecording",
+					message: cause instanceof Error ? cause.message : String(cause),
+					cause
+				}
+			});
+		}
+		const backend = this.backend;
+		return {
+			id,
+			get state() {
+				return attempt.state;
+			},
+			get elapsedMs() {
+				return attempt.state === "recording" || attempt.state === "finalizing" ? backend.elapsedMs() : 0;
+			},
+			completion,
+			stop: () => {
+				if (this.attempt?.id === id) this.requestStop("stopped");
+				return completion;
+			}
+		};
+	}
+	openOutput(output) {
+		return this.backend.openOutput(output);
+	}
+	async dispose() {
+		if (this.disposed) return;
+		this.disposeRequested = true;
+		const attempt = this.attempt;
+		if (attempt && attempt.state !== "settled") {
+			this.requestStop("disposed");
+			await attempt.completion;
+		}
+		await this.finishDispose();
+	}
+	async finishDispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.backend.setObserver(void 0);
+		try {
+			await this.backend.release();
+		} finally {
+			this.setState("disposed");
+		}
+	}
+};
+//#endregion
+export { SharedCameraSession };

package/dist/web/session.js

@@ -0,0 +1,29 @@
+import { CameraCaptureError } from "./types.js";
+import { SharedCameraSession } from "./session-core.js";
+import { createSessionBackend } from "./session-backend.web.js";
+//#region src/session.ts
+/** Create a shared camera owner: one acquisition shared between a
+*  `CameraView` preview (`session` prop) and at most one movie-recording
+*  attempt. Creating a session never prompts for permission or acquires
+*  hardware — both happen when a session-backed preview activates or a
+*  permission request runs.
+*
+*  Recording support is delivered per platform; `capabilities()` reports
+*  honest `supported`/`available` state on every host. */
+function createCameraSession(config = {}) {
+	return new SharedCameraSession(createSessionBackend(config), config);
+}
+/** Package-internal: attach `host` as the session's preview surface.
+*  Used by `CameraView` when its `session` prop is set; detaching the
+*  returned function requests stop on an in-flight attempt and releases
+*  camera ownership once finalization settles. */
+function attachSessionPreview(session, host, listener) {
+	if (!(session instanceof SharedCameraSession)) throw new CameraCaptureError({
+		kind: "invalidArgument",
+		operation: "attachPreview",
+		message: "session was not created by createCameraSession"
+	});
+	return session.attach(host, listener);
+}
+//#endregion
+export { attachSessionPreview, createCameraSession };

package/dist/web/synthetic-session.js

@@ -0,0 +1,280 @@
+import { SharedCameraSession } from "./session-core.js";
+//#region src/synthetic-session.ts
+/** In-memory storage for the seam — a `fileUrl`-shaped map so outcomes
+*  exercise the same reopen path without touching a real filesystem. */
+function createMemoryCameraStorage() {
+	const files = /* @__PURE__ */ new Map();
+	return {
+		files,
+		write: (path, bytes) => {
+			files.set(path, bytes);
+		},
+		read: (path) => files.get(path),
+		delete: (path) => {
+			files.delete(path);
+		},
+		exists: (path) => files.has(path)
+	};
+}
+var defaultScript = () => ({
+	permission: {
+		camera: "granted",
+		microphone: "granted"
+	},
+	available: true,
+	startDelayMs: 20,
+	clipDurationMs: 3e3,
+	produceMedia: true
+});
+var capabilities = {
+	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. */
+function createSyntheticCameraSession(config = {}, script = {}, storage = createMemoryCameraStorage()) {
+	const controls = {
+		...defaultScript(),
+		...script
+	};
+	return new SharedCameraSession(createSyntheticBackend(controls, storage), config);
+}
+function createSyntheticBackend(script, storage) {
+	let observer;
+	let attached = false;
+	let sink;
+	let startedAt;
+	let timers = [];
+	let pendingRequest;
+	const later = (ms, fn) => {
+		timers.push(setTimeout(fn, ms));
+	};
+	const clearTimers = () => {
+		for (const timer of timers) clearTimeout(timer);
+		timers = [];
+	};
+	const settleClip = async (request, limitReached) => {
+		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 {
+			await storage.write(path, new Uint8Array([
+				120,
+				112,
+				108,
+				97,
+				116
+			]));
+		} catch (cause) {
+			sink?.settled({
+				kind: "failed",
+				stage: "storage",
+				issue: {
+					kind: "storageFailed",
+					operation: "store",
+					message: cause instanceof Error ? cause.message : String(cause),
+					cause
+				}
+			});
+			return;
+		}
+		const settle = {
+			kind: "clip",
+			output: {
+				kind: "nativeFile",
+				resourceId: `synthetic:${path}`,
+				fileUrl: `file://${path}`,
+				synthetic: true
+			},
+			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 ? void 0 : "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 !== void 0) later(script.interruption.endsAfterMs, () => {
+						observer?.interruption("ended", script.interruption?.reason);
+					});
+				});
+				if (request.maximumDurationMs !== void 0) later(request.maximumDurationMs, () => {
+					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: () => {
+			const request = pendingRequest;
+			later(5, () => {
+				if (request) settleClip(request, false);
+			});
+		},
+		elapsedMs: () => startedAt === void 0 ? 0 : Date.now() - startedAt,
+		openOutput: async (output) => {
+			const path = output.kind === "nativeFile" ? output.fileUrl.slice(7) : "";
+			if (!(storage.exists ? await storage.exists(path) : !!await storage.read(path))) 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 : void 0,
+				release: () => {}
+			};
+		},
+		release: async () => {
+			attached = false;
+			clearTimers();
+			sink = void 0;
+			startedAt = void 0;
+			pendingRequest = void 0;
+		},
+		onPreviewDetached: () => {},
+		setObserver: (next) => {
+			observer = next;
+		}
+	};
+}
+//#endregion
+export { createMemoryCameraStorage, createSyntheticCameraSession };

package/dist/web/types.js

@@ -0,0 +1,19 @@
+//#region src/types.ts
+/** Error thrown or settled by the session API. Satisfies `CaptureIssue`
+*  so `error.kind` drives control flow without unwrapping. */
+var CameraCaptureError = class extends Error {
+	kind;
+	operation;
+	permission;
+	cause;
+	constructor(issue) {
+		super(issue.message);
+		this.name = "CameraCaptureError";
+		this.kind = issue.kind;
+		this.operation = issue.operation;
+		this.permission = issue.permission;
+		this.cause = issue.cause;
+	}
+};
+//#endregion
+export { CameraCaptureError };