@octane-xplat/camera 0.13.0 → 0.14.0

package/README.md

@@ -5,7 +5,9 @@ pnpm add @octane-xplat/camera
 ```
 
 Live camera preview for Octane xplat apps: `getUserMedia` video on web,
-`AVCaptureSession` on iOS, CameraX on Android.
+`AVCaptureSession` on iOS, CameraX on Android,
+`AVCaptureSession` + `AVCaptureVideoPreviewLayer` on macOS (AppKit), and
+`MediaCapture` + `CaptureElement` on the Windows (WinUI 3) target.
 
 ```tsx
 import { CameraView } from '@octane-xplat/camera'
@@ -26,8 +28,11 @@ This is the preview surface only — for one-shot still capture and library
 picking use [`@octane-xplat/media`](../media/README.md). Permissions are
 requested when the session starts; `onError` is how a denial shows up.
 `ref` hands you the platform surface (`HTMLVideoElement` on web) for
-controls the shared props don't cover, and the `ios`/`android`/`web`
-escape props apply after the shared props.
+controls the shared props don't cover, and the `ios`/`android`/`web`/
+`windows` escape props apply after the shared props. On macOS the leaf is a
+compiled Swift `XplatCameraHost` that owns the capture session; the app bundle
+needs `NSCameraUsageDescription` (and `NSMicrophoneUsageDescription` for
+audio) declared through `xplat.targets.macos.package.infoPlist`.
 
 ```tsx
 // Preview.web.tsx — browser properties belong in this platform file.
@@ -44,6 +49,61 @@ export function Preview() {
 }
 ```
 
+## Movie recording
+
+`createCameraSession` creates a shared camera owner: the same session can
+drive a `CameraView` preview and one movie-recording attempt at a time.
+Pass the session to `CameraView` instead of `facing`; the preview attaches
+the camera the session owns. Recording requires an attached, ready preview.
+
+```tsx
+import { CameraView, createCameraSession } from '@octane-xplat/camera'
+
+const session = createCameraSession({ camera: 'default' })
+
+export function Recorder() {
+	return <CameraView session={session} />
+}
+```
+
+A take settles after the movie is finalized, metadata is verified, and local
+storage is committed. Native output lives in app-private files — including the
+packaged Linux WebKitGTK host, which writes under the app's data directory;
+Web uses persistent origin storage. Reopen it with `session.openOutput(output)`.
+
+```ts
+const take = session.startRecording({ maximumDurationMs: 30_000 })
+// … later, on a stop press or a maximum-duration limit:
+const outcome = await take.stop()
+if (outcome.kind === 'clip') {
+	const clip = outcome.clip
+	console.log(clip.durationMs, clip.width, clip.height, clip.output)
+}
+```
+
+One preview and one recording per session; a second `startRecording` throws
+`CameraCaptureError` with `kind: 'busy'`. Check `session.capabilities()` for
+`supported`/`available` before presenting capture UI, and `session.snapshot()`
+or `session.subscribe` for state. iOS, Android, Web, macOS, the Windows WinUI
+target, and the packaged Linux WebKitGTK host have recording adapters; Web
+requires persistent origin storage.
+macOS writes app-private MOV files through `AVCaptureMovieFileOutput` and
+reports finalized track metadata; on macOS 14+ the four cardinal orientations
+are lockable. Inside a qualified `xplat` WKWebView host the Web backend stores
+output in the app's private storage root instead of IndexedDB. Windows records
+through `MediaCapture` into app-private MP4 files and is pending real-host
+qualification. On Linux the GJS/WebKitGTK host owns media permissions and
+writes MP4 clips under the app's data directory.
+See [Record and reopen a camera movie](../../docs/app/movie-capture.md) for
+explicit permission actions, audio, local output, and qualification limits.
+
+```ts
+console.log(await session.permissions())
+// Call from an app button:
+await session.requestPermission('camera')
+console.log(await session.capabilities())
+```
+
 Guide: [Building screens](../../docs/app/primitives.md) (leaf components);
 component index: [`docs/app/components.md`](../../docs/app/components.md).
 Exercised by [`CameraDemo`](../demos/src/CameraDemo.tsrx).

package/dist/linux/CameraView.web.tsrx.js

@@ -0,0 +1,337 @@
+import { attachSessionPreview } from "./session.js";
+import { applyEscapeProps, layoutChildProps } from "./layout-child.web.js";
+import { __s, bag15, bag5, child, clone, delegateEvents, evt2e, evt2u, hookSlots, ifBlock, markDangerouslySetInnerHTMLChildren, queueRefAttach, queueRefDetach, setStyleProperty, snapshotSpread, template, useEffect, useImperativeHandle, useRef } from "octane";
+import { bindSignalHostPropSources, enableSignalBindings, replaceRef, setAttributeIfChanged } from "octane/internal/client";
+//#region src/CameraView.web.tsrx
+enableSignalBindings(1, true);
+delegateEvents(["playing"]);
+var _t$0 = /* @__PURE__ */ template("<video autoplay=\"\" playsinline=\"\" style=\"display: block; width: 100%; height: 100%; object-fit: cover;\"></video>");
+var _t$1 = /* @__PURE__ */ template("<div><!></div>");
+var _hs$ = /* @__PURE__ */ hookSlots(5);
+var __event = (__eventArg, props, readyFired) => {
+	if (props.session || readyFired.current) return;
+	readyFired.current = true;
+	props.onReady?.();
+};
+var _rm$1 = [
+	"r",
+	"b",
+	"a"
+];
+function __then$0(__props, __s, __extra) {
+	const facing = __extra[0];
+	const hostRef = __extra[1];
+	const props = __extra[2];
+	const readyFired = __extra[3];
+	const video = __extra[4];
+	let _b = __s.slots[0];
+	if (_b === void 0) {
+		let _m1, _m4;
+		const _root = clone(_t$0, void 0, "||");
+		queueRefAttach(__s, _m1 = (element) => {
+			hostRef.current = element;
+			video.current = element;
+			if (!element) return;
+			applyEscapeProps(element, props);
+		}, _root);
+		(__s.cleanups ??= []).push(() => _b && queueRefDetach(_b.b, _b.a));
+		_m4 = evt2e(_root, "$oplaying", __event, props, readyFired);
+		_b = bag5(__s, _root, _root, _m1, void 0, __s, _m4);
+		__s.refFields = _rm$1;
+	} else {
+		{
+			const _r = (element) => {
+				hostRef.current = element;
+				video.current = element;
+				if (!element) return;
+				applyEscapeProps(element, props);
+			};
+			if (_r !== _b.b) _b.b = replaceRef(__s, _b.b, _r, _b.a);
+		}
+		evt2u(_b.e, __event, props, readyFired);
+	}
+	_b.c = setAttributeIfChanged(true, _b.c, _b.a, "muted");
+	{
+		const _v = facing === "front" ? "scaleX(-1)" : void 0;
+		if (_b.d !== _v) {
+			setStyleProperty(_b.a, "transform", _v, "display: block; width: 100%; height: 100%; object-fit: cover;", _b.d);
+			_b.d = _v;
+		}
+	}
+}
+var _rm$3 = [
+	"s",
+	"n",
+	"m"
+];
+var CameraView = /* @__PURE__ */ __s(function CameraView(props, __s, __extra) {
+	const hostRef = useRef(null, _hs$ + 0);
+	const video = useRef(null, _hs$ + 1);
+	const facing = props.facing ?? "back";
+	const active = props.active !== false;
+	const readyFired = useRef(false, _hs$ + 2);
+	useEffect(() => {
+		const element = video.current;
+		if (!element || !active) return;
+		if (props.session) {
+			if (props.facing !== void 0) {
+				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) {
+				props.onError?.({ message: error?.message ?? "camera session error" });
+				return;
+			}
+		}
+		const mediaDevices = navigator.mediaDevices;
+		if (!mediaDevices?.getUserMedia) {
+			props.onError?.({ message: "camera unsupported" });
+			return;
+		}
+		let stream = null;
+		let disposed = false;
+		readyFired.current = false;
+		mediaDevices.getUserMedia({
+			video: { facingMode: facing === "front" ? "user" : "environment" },
+			audio: false
+		}).then((nextStream) => {
+			if (disposed) {
+				for (const track of nextStream.getTracks()) track.stop();
+				return;
+			}
+			stream = nextStream;
+			element.srcObject = nextStream;
+			element.play()?.catch(() => {});
+		}).catch((error) => {
+			props.onError?.({ message: error?.name === "NotAllowedError" ? "camera permission denied" : String(error?.name ?? error ?? "camera error") });
+		});
+		return () => {
+			disposed = true;
+			element.srcObject = null;
+			if (stream) for (const track of stream.getTracks()) track.stop();
+		};
+	}, [
+		active,
+		facing,
+		props.session
+	], _hs$ + 3);
+	useImperativeHandle(props.ref, () => ({ native: hostRef.current }), void 0, _hs$ + 4);
+	let _b = __s.slots[0];
+	if (_b === void 0) {
+		let _m0, _m1, _m2, _m3, _m4, _m5, _m6, _m7, _m8, _m9, _m10, _m11, _m13, _m14;
+		const _root = clone(_t$1);
+		_m0 = props.id;
+		_m1 = [
+			"vx-layers",
+			"vx-cameraview",
+			props.className
+		];
+		_m2 = snapshotSpread(layoutChildProps(props, {
+			position: "relative",
+			overflow: "hidden",
+			backgroundColor: "#000",
+			...props.style
+		}));
+		_m3 = props.accessibilityRole;
+		_m4 = props.accessibilityLabel;
+		_m5 = props.accessible === false ? true : void 0;
+		_m6 = props.accessibilityHint;
+		_m7 = props.accessibilityValue;
+		_m8 = props.accessibilityState?.disabled;
+		_m9 = props.accessibilityState?.selected;
+		_m10 = props.accessibilityState?.checked;
+		_m11 = props.accessibilityLiveRegion === "none" ? "off" : props.accessibilityLiveRegion;
+		_m13 = bindSignalHostPropSources(__s, void 0, _root, [
+			[
+				false,
+				"id",
+				_m0
+			],
+			[
+				false,
+				"className",
+				_m1
+			],
+			[true, _m2],
+			[
+				false,
+				"role",
+				_m3
+			],
+			[
+				false,
+				"aria-label",
+				_m4
+			],
+			[
+				false,
+				"aria-hidden",
+				_m5
+			],
+			[
+				false,
+				"aria-description",
+				_m6
+			],
+			[
+				false,
+				"aria-valuetext",
+				_m7
+			],
+			[
+				false,
+				"aria-disabled",
+				_m8
+			],
+			[
+				false,
+				"aria-selected",
+				_m9
+			],
+			[
+				false,
+				"aria-checked",
+				_m10
+			],
+			[
+				false,
+				"aria-live",
+				_m11
+			]
+		], "b:d3c40afd", true);
+		markDangerouslySetInnerHTMLChildren(_root);
+		_m14 = child(_root);
+		_b = bag15(__s, _root, _m0, _m1, _m2, _m3, _m4, _m5, _m6, _m7, _m8, _m9, _m10, _m11, _root, _m13, _m14);
+		__s.refFields = _rm$3;
+	} else {
+		{
+			const _v = props.id;
+			if (_b.a !== _v) _b.a = _v;
+		}
+		{
+			const _v = [
+				"vx-layers",
+				"vx-cameraview",
+				props.className
+			];
+			if (_b.b !== _v) _b.b = _v;
+		}
+		_b.c = snapshotSpread(layoutChildProps(props, {
+			position: "relative",
+			overflow: "hidden",
+			backgroundColor: "#000",
+			...props.style
+		}));
+		{
+			const _v = props.accessibilityRole;
+			if (_b.d !== _v) _b.d = _v;
+		}
+		{
+			const _v = props.accessibilityLabel;
+			if (_b.e !== _v) _b.e = _v;
+		}
+		{
+			const _v = props.accessible === false ? true : void 0;
+			if (_b.f !== _v) _b.f = _v;
+		}
+		{
+			const _v = props.accessibilityHint;
+			if (_b.g !== _v) _b.g = _v;
+		}
+		{
+			const _v = props.accessibilityValue;
+			if (_b.h !== _v) _b.h = _v;
+		}
+		{
+			const _v = props.accessibilityState?.disabled;
+			if (_b.i !== _v) _b.i = _v;
+		}
+		{
+			const _v = props.accessibilityState?.selected;
+			if (_b.j !== _v) _b.j = _v;
+		}
+		{
+			const _v = props.accessibilityState?.checked;
+			if (_b.k !== _v) _b.k = _v;
+		}
+		{
+			const _v = props.accessibilityLiveRegion === "none" ? "off" : props.accessibilityLiveRegion;
+			if (_b.l !== _v) _b.l = _v;
+		}
+		_b.n = bindSignalHostPropSources(__s, _b.n, _b.m, [
+			[
+				false,
+				"id",
+				_b.a
+			],
+			[
+				false,
+				"className",
+				_b.b
+			],
+			[true, _b.c],
+			[
+				false,
+				"role",
+				_b.d
+			],
+			[
+				false,
+				"aria-label",
+				_b.e
+			],
+			[
+				false,
+				"aria-hidden",
+				_b.f
+			],
+			[
+				false,
+				"aria-description",
+				_b.g
+			],
+			[
+				false,
+				"aria-valuetext",
+				_b.h
+			],
+			[
+				false,
+				"aria-disabled",
+				_b.i
+			],
+			[
+				false,
+				"aria-selected",
+				_b.j
+			],
+			[
+				false,
+				"aria-checked",
+				_b.k
+			],
+			[
+				false,
+				"aria-live",
+				_b.l
+			]
+		], "b:d3c40afd", true);
+	}
+	{
+		const __ifCondition = active;
+		ifBlock(__s, 1, _b.m, __ifCondition, __then$0, null, _b.o, __ifCondition ? [
+			facing,
+			hostRef,
+			props,
+			readyFired,
+			video
+		] : void 0, 1);
+	}
+});
+//#endregion
+export { CameraView };

package/dist/linux/host-movie.web.js

@@ -0,0 +1,100 @@
+import { CameraCaptureError } from "./types.js";
+import { createHostClient } from "@octane-xplat/platform/host";
+import { createWebKitTransport } from "@octane-xplat/platform/host/web";
+//#region src/host-movie.web.ts
+var requiredMethods = [
+	"permissionStatus",
+	"requestPermission",
+	"movieDirectory",
+	"reserveMoviePath",
+	"writeMovieFile",
+	"movieFileInfo",
+	"readMovieFile",
+	"deleteMovieFile"
+];
+var hostProbe;
+/** The camera-capable desktop host client, or null outside a qualified host. */
+function cameraHost() {
+	hostProbe ??= (async () => {
+		try {
+			const transport = createWebKitTransport();
+			if (!transport) return null;
+			const client = createHostClient(transport);
+			const methods = (await client.capabilities().catch(() => null))?.camera;
+			if (Array.isArray(methods) && requiredMethods.every((name) => methods.includes(name))) return client;
+			client.dispose();
+			return null;
+		} catch {
+			return null;
+		}
+	})();
+	return hostProbe;
+}
+var error = (kind, message) => new CameraCaptureError({
+	kind,
+	operation: "storage",
+	message
+});
+var blobToBase64 = async (bytes) => {
+	const data = new Uint8Array(await bytes.arrayBuffer());
+	let binary = "";
+	const chunk = 32768;
+	for (let offset = 0; offset < data.length; offset += chunk) binary += String.fromCharCode(...data.subarray(offset, offset + chunk));
+	return btoa(binary);
+};
+var base64ToBlob = (base64, type) => {
+	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 });
+};
+var mimeForFileUrl = (fileUrl) => 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. */
+var reserveHostMovie = async (host, options) => {
+	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. */
+var commitHostMovie = async (host, fileUrl, bytes) => {
+	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. */
+var removeHostReservation = async (host, fileUrl) => {
+	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()`. */
+var openHostMovie = async (host, output) => {
+	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)
+	};
+};
+//#endregion
+export { cameraHost, commitHostMovie, openHostMovie, removeHostReservation, reserveHostMovie };

package/dist/linux/index.js

@@ -0,0 +1,5 @@
+import { CameraCaptureError } from "./types.js";
+import { createCameraSession } from "./session.js";
+import { CameraView } from "./CameraView.web.tsrx.js";
+import { createMemoryCameraStorage, createSyntheticCameraSession } from "./synthetic-session.js";
+export { CameraCaptureError, CameraView, createCameraSession, createMemoryCameraStorage, createSyntheticCameraSession };

package/dist/linux/layout-child.web.js

@@ -0,0 +1,29 @@
+//#region src/layout-child.web.ts
+function layoutChildProps(props, baseStyle = props.style) {
+	const style = { ...baseStyle };
+	if (props.row !== void 0) style.gridRow = `${props.row + 1} / span ${props.rowSpan ?? 1}`;
+	else if (props.rowSpan !== void 0) style.gridRow = `span ${props.rowSpan}`;
+	if (props.col !== void 0) style.gridColumn = `${props.col + 1} / span ${props.colSpan ?? 1}`;
+	else if (props.colSpan !== void 0) style.gridColumn = `span ${props.colSpan}`;
+	if (props.left !== void 0) style.left = props.left;
+	if (props.top !== void 0) style.top = props.top;
+	if (props.flexGrow !== void 0) style.flexGrow = props.flexGrow;
+	if (props.flexShrink !== void 0) style.flexShrink = props.flexShrink;
+	if (props.alignSelf !== void 0) style.alignSelf = props.alignSelf;
+	if (props.order !== void 0) style.order = props.order;
+	return { style };
+}
+function applyEscapeProps(element, props) {
+	if (!element || !props.web) return;
+	for (const [key, value] of Object.entries(props.web)) if (key.includes("-")) {
+		if (value == null || value === false) element.removeAttribute(key);
+		else element.setAttribute(key, value === true ? "" : String(value));
+	} else if (key in element) try {
+		element[key] = value;
+	} catch {
+		element.setAttribute(key, String(value));
+	}
+	else if (value != null) element.setAttribute(key, String(value));
+}
+//#endregion
+export { applyEscapeProps, layoutChildProps };

package/dist/linux/movie-metadata.web.js

@@ -0,0 +1,65 @@
+import { CameraCaptureError } from "./types.js";
+import { BlobSource, Input, MP4, WEBM } from "mediabunny";
+//#region src/movie-metadata.web.ts
+/** Read packet end timestamps and track metadata, never the wall-clock stop time. */
+async function inspectMovie(bytes, audioRequested) {
+	if (!bytes.size) throw new CameraCaptureError({
+		kind: "noMedia",
+		operation: "finalize",
+		message: "The recorder produced no movie bytes"
+	});
+	const input = new Input({
+		source: new BlobSource(bytes),
+		formats: [WEBM, MP4]
+	});
+	const read = async () => {
+		const video = await input.getPrimaryVideoTrack();
+		const audio = await input.getPrimaryAudioTrack();
+		if (!video) throw new CameraCaptureError({
+			kind: "noMedia",
+			operation: "finalize",
+			message: "The movie contains no video track"
+		});
+		const videoDuration = await video.computeDuration();
+		const hasAudio = audio !== null && await audio.computeDuration() > 0;
+		const durationMs = await input.computeDuration() * 1e3;
+		const width = await video.getDisplayWidth();
+		const height = await video.getDisplayHeight();
+		if (!Number.isFinite(durationMs) || durationMs <= 0 || videoDuration <= 0 || width <= 0 || height <= 0) throw new CameraCaptureError({
+			kind: "noMedia",
+			operation: "finalize",
+			message: "The movie has no usable video media"
+		});
+		if (audioRequested && !hasAudio) throw new CameraCaptureError({
+			kind: "captureFailed",
+			operation: "finalize",
+			message: "Requested audio is absent from the finalized movie"
+		});
+		return {
+			durationMs,
+			width,
+			height,
+			hasAudio,
+			mimeType: await input.getMimeType(),
+			orientation: "unspecified"
+		};
+	};
+	let timer;
+	try {
+		return await Promise.race([read(), new Promise((_resolve, reject) => {
+			timer = setTimeout(() => {
+				input.dispose();
+				reject(new CameraCaptureError({
+					kind: "finalizationFailed",
+					operation: "metadata",
+					message: "Movie metadata verification timed out"
+				}));
+			}, 3e4);
+		})]);
+	} finally {
+		clearTimeout(timer);
+		input.dispose();
+	}
+}
+//#endregion
+export { inspectMovie };

package/dist/linux/octane-client-build.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "13c3f733-39bd-4532-b458-4284c848f839",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}