@octane-xplat/camera 0.14.0 → 0.15.0

package/README.md

@@ -49,6 +49,32 @@ export function Preview() {
 }
 ```
 
+## Tap-to-focus
+
+`CameraView` reports where the user tapped as a normalized point —
+`{x: 0, y: 0}` is the top-left corner of the preview, `{x: 1, y: 1}` the
+bottom-right. Hand the point to a session's `focusAtPoint` to meter one
+autofocus and auto-exposure pass there:
+
+```tsx
+import { CameraView, createCameraSession } from '@octane-xplat/camera'
+
+const session = createCameraSession()
+
+export function FocusablePreview() {
+	return <CameraView session={session} onTap={(point) => session.focusAtPoint(point)} />
+}
+```
+
+`onTap` is a pure notification — it never takes over the gesture, so
+double-tap and pan recognizers layered over the preview keep working.
+`focusAtPoint` needs a session (it drives the camera the preview
+attaches) and quietly does nothing on cameras that cannot meter at a
+point — front cameras are often fixed-focus. Check
+`capabilities().focusPointOfInterest` and `exposurePointOfInterest`
+before showing focus UI. Metering lands on iOS, Android, and macOS; the
+tap event fires on iOS, Android, and web.
+
 ## Movie recording
 
 `createCameraSession` creates a shared camera owner: the same session can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/camera",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Live camera preview for Octane xplat — web getUserMedia + native capture (AVCapture / CameraX)",
   "keywords": [
     "android",
@@ -23,33 +23,39 @@
     "directory": "packages/camera"
   },
   "files": [
-    "dist",
     "types",
     "src",
-    "platforms"
+    "platforms",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
   ],
   "type": "module",
   "exports": {
     ".": {
       "types": "./types/index.d.ts",
-      "linux": "./dist/linux/index.js",
-      "web": "./dist/web/index.js",
-      "native": "./dist/native/index.js",
-      "default": "./dist/native/index.js"
+      "linux": "./src/index.web.ts",
+      "web": "./src/index.web.ts",
+      "native": "./src/index.ts",
+      "default": "./src/index.ts"
     }
   },
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@octane-xplat/platform": "0.15.0",
+    "mediabunny": "1.61.3"
+  },
   "devDependencies": {
-    "@nativescript-community/octane": "0.2.4",
+    "@nativescript-community/octane": "0.2.5",
     "@nativescript/core": "9.1.3",
+    "@octane-xplat/macos-renderer": "0.15.0",
     "@octanejs/vite-plugin": "0.1.61",
     "octane": "0.11.0",
-    "tsrx-typegen": "0.2.2",
+    "tsrx-typegen": "0.3.0",
     "typescript": "5.9.3",
     "vite": "8.3.0",
-    "vitest": "5.0.1"
+    "vitest": "4.1.11"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
@@ -73,12 +79,11 @@
       "android": "7.0.0"
     }
   },
-  "dependencies": {
-    "@octane-xplat/platform": "0.14.0",
-    "mediabunny": "1.61.3"
-  },
   "xplat": {
     "macos": {
+      "swiftHeaderImports": [
+        "AppKit/AppKit.h"
+      ],
       "frameworks": [
         "AVFoundation",
         "CoreMedia",
@@ -87,11 +92,12 @@
     }
   },
   "scripts": {
-    "build": "vite build && vite build --mode native && vite build --mode linux && pnpm typegen && node ../../scripts/check-native-dist.mjs",
     "typegen": "tsc -p tsconfig.types.json",
     "test:packed": "node tests/packed-consumer.mjs",
     "pack:check": "tsrx-typegen --pack-check",
-    "test": "vitest run",
+    "test": "vitest run && node --test tests/*.test.mjs",
+    "test:macos-photo": "node tests/photo-native.macos.mjs",
+    "test:macos-photo-hardware": "node tests/photo-hardware.macos.mjs",
     "test:web": "node tests/browser-conformance.web.mjs",
     "test:webkitgtk": "node tests/webkitgtk-conformance.linux.mjs"
   }

package/platforms/android/java/com/octanexplat/camera/CameraPreviewView.java

@@ -4,6 +4,7 @@ import android.content.Context;
 import android.view.ViewGroup;
 import android.widget.FrameLayout;
 
+import androidx.camera.core.MeteringPoint;
 import androidx.camera.core.Preview;
 import androidx.camera.view.PreviewView;
 import androidx.lifecycle.Lifecycle;
@@ -45,6 +46,14 @@ public final class CameraPreviewView extends FrameLayout implements LifecycleOwn
 		return previewView.getSurfaceProvider();
 	}
 
+	/** Converts a normalized view-space point (0-1, top-left origin) into a
+	 *  CameraX metering point. The PreviewView factory accounts for scale
+	 *  type, rotation, and front-camera mirroring. */
+	public MeteringPoint meteringPoint(float x, float y) {
+		return previewView.getMeteringPointFactory().createPoint(
+			x * previewView.getWidth(), y * previewView.getHeight());
+	}
+
 	public androidx.lifecycle.LiveData<PreviewView.StreamState> getStreamState() {
 		return previewView.getPreviewStreamState();
 	}

package/platforms/android/java/com/octanexplat/camera/CameraSessionBridge.java

@@ -17,6 +17,8 @@ import androidx.camera.core.CameraInfo;
 import androidx.camera.core.CameraSelector;
 import androidx.camera.core.CameraState;
 import androidx.camera.core.DynamicRange;
+import androidx.camera.core.FocusMeteringAction;
+import androidx.camera.core.MeteringPoint;
 import androidx.camera.core.MirrorMode;
 import androidx.camera.core.Preview;
 import androidx.camera.lifecycle.ProcessCameraProvider;
@@ -38,6 +40,7 @@ import java.io.FileInputStream;
 import java.io.FileOutputStream;
 import java.util.Collections;
 import java.util.UUID;
+import java.util.concurrent.TimeUnit;
 import org.json.JSONArray;
 import org.json.JSONObject;
 
@@ -199,9 +202,37 @@ public final class CameraSessionBridge implements LifecycleOwner {
 				Size size = video.getResolutionInfo().getResolution();
 				profiles.put(new JSONObject().put("profile", "standard").put("width", size.getWidth()).put("height", size.getHeight()).put("frameRate", Math.round(sourceFrameRate * 100.0) / 100.0));
 			}
+			if (camera != null && host != null && host.getWidth() > 0) {
+				MeteringPoint center = host.meteringPoint(0.5f, 0.5f);
+				result.put("focusPointOfInterest", camera.getCameraInfo().isFocusMeteringSupported(
+					new FocusMeteringAction.Builder(center, FocusMeteringAction.FLAG_AF).build()));
+				result.put("exposurePointOfInterest", camera.getCameraInfo().isFocusMeteringSupported(
+					new FocusMeteringAction.Builder(center, FocusMeteringAction.FLAG_AE).build()));
+			}
 			return result.put("cameras", cameras).put("profiles", profiles).toString();
 		} catch (Exception cause) { return "{\"cameras\":[],\"profiles\":[]}"; }
 	}
+	/** Tap-to-focus: one AF+AE metering pass at a normalized preview point
+	 *  (0-1, top-left origin as the user sees it). Metering auto-cancels
+	 *  after three seconds rather than locking. Returns false when no
+	 *  camera is bound or the device cannot meter at a point. */
+	public boolean focusAtPoint(float x, float y) {
+		if (camera == null || host == null || detached || released || host.getWidth() <= 0) {
+			return false;
+		}
+		try {
+			MeteringPoint point = host.meteringPoint(x, y);
+			FocusMeteringAction action = new FocusMeteringAction.Builder(
+				point, FocusMeteringAction.FLAG_AF | FocusMeteringAction.FLAG_AE)
+				.setAutoCancelDuration(3, TimeUnit.SECONDS)
+				.build();
+			if (!camera.getCameraInfo().isFocusMeteringSupported(action)) return false;
+			camera.getCameraControl().startFocusAndMetering(action);
+			return true;
+		} catch (Exception cause) {
+			return false;
+		}
+	}
 	private String orientation() {
 		// Display rotation is not a cardinal camera orientation on every device.
 		return "unspecified";

package/platforms/macos/src/CameraOwnership.swift

@@ -0,0 +1,22 @@
+import Foundation
+
+/// Shared by preview, movie and still-photo hosts. A busy source is never stolen.
+enum CameraOwnership {
+	private static let lock = NSLock()
+	private static var owners: [String: ObjectIdentifier] = [:]
+
+	static func claim(_ id: String, owner: AnyObject) -> Bool {
+		lock.lock()
+		defer { lock.unlock() }
+		let token = ObjectIdentifier(owner)
+		guard owners[id] == nil || owners[id] == token else { return false }
+		owners[id] = token
+		return true
+	}
+
+	static func release(_ id: String, owner: AnyObject) {
+		lock.lock()
+		defer { lock.unlock() }
+		if owners[id] == ObjectIdentifier(owner) { owners.removeValue(forKey: id) }
+	}
+}

package/platforms/macos/src/PhotoCaptureLifecycle.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+/// Fences every asynchronous permission, preview and shutter result.
+final class PhotoCaptureLifecycle {
+	enum Phase { case idle, preparing, preview, capturing, finished }
+	private(set) var phase = Phase.idle
+	private(set) var generation = 0
+	var finished: (() -> Void)?
+
+	func prepare() -> Int? {
+		guard phase == .idle else { return nil }
+		phase = .preparing
+		return generation
+	}
+	func ready(_ token: Int) -> Bool {
+		guard accepts(token), phase == .preparing else { return false }
+		phase = .preview
+		return true
+	}
+	func capture() -> Int? {
+		guard phase == .preview else { return nil }
+		phase = .capturing
+		return generation
+	}
+	func accepts(_ token: Int) -> Bool { phase != .finished && token == generation }
+	@discardableResult func finish() -> Bool {
+		guard phase != .finished else { return false }
+		phase = .finished
+		generation += 1
+		finished?()
+		finished = nil
+		return true
+	}
+}

package/platforms/macos/src/XplatCameraHost.swift

@@ -90,12 +90,26 @@ private final class XplatRecordingDelegate: NSObject, AVCaptureFileOutputRecordi
 	}
 }
 
+private final class XplatPhotoDelegate: NSObject, AVCapturePhotoCaptureDelegate {
+	var reply: ((Data?) -> Void)?
+	func photoOutput(_ output: AVCapturePhotoOutput, didFinishProcessingPhoto photo: AVCapturePhoto, error: Error?) {
+		let data = error == nil ? photo.fileDataRepresentation() : nil
+		DispatchQueue.main.async { [self] in
+			reply?(data)
+			reply = nil
+		}
+	}
+}
+
 @objc(XplatCameraHost)
 public final class XplatCameraHost: NSObject {
 	private var session: AVCaptureSession?
 	private var videoInput: AVCaptureDeviceInput?
 	private var audioInput: AVCaptureDeviceInput?
 	private var movieOutput: AVCaptureMovieFileOutput?
+	private var photoOutput: AVCapturePhotoOutput?
+	private var photoDelegate: XplatPhotoDelegate?
+	private var claimedCameraIds: Set<String> = []
 	private var previewLayer: AVCaptureVideoPreviewLayer?
 	private weak var previewView: NSView?
 	private var configuredCameraId: String?
@@ -190,7 +204,13 @@ public final class XplatCameraHost: NSObject {
 
 	@objc public func devices() -> NSString {
 		let list: [[String: Any]] = cameraDevices().map {
-			["id": $0.uniqueID, "name": $0.localizedName, "facing": NSNull()]
+			[
+				"id": $0.uniqueID,
+				"name": $0.localizedName,
+				"facing": NSNull(),
+				"focusPointOfInterest": $0.isFocusPointOfInterestSupported,
+				"exposurePointOfInterest": $0.isExposurePointOfInterestSupported,
+			]
 		}
 		guard
 			let data = try? JSONSerialization.data(withJSONObject: list),
@@ -291,11 +311,14 @@ public final class XplatCameraHost: NSObject {
 	}
 
 	@objc public func configure(_ options: NSDictionary) -> NSString? {
+		guard !disposed else { return "unavailable" }
 		guard let session = ensureSession() else { return "permissionDenied" }
 		var failure: String?
 		queue.sync {
+			guard !disposed else { failure = "unavailable"; return }
 			let cameraId = options["cameraId"] as? String
-			let audio = options["audio"] as? Bool ?? false
+			let photo = options["photo"] as? Bool ?? false
+			let audio = !photo && (options["audio"] as? Bool ?? false)
 			rotationAngle = (options["rotationAngle"] as? NSNumber)?.doubleValue
 			let devices = cameraDevices()
 			guard let device = cameraId != nil
@@ -306,6 +329,21 @@ public final class XplatCameraHost: NSObject {
 				return
 			}
 
+			guard CameraOwnership.claim(device.uniqueID, owner: self) else {
+				failure = "busy"
+				return
+			}
+			claimedCameraIds.insert(device.uniqueID)
+			defer {
+				// Failed reconfiguration may retain either input. Hold both claims
+				// until disposal rather than admitting an overlapping session.
+				if failure == nil {
+					for old in claimedCameraIds where old != device.uniqueID {
+						CameraOwnership.release(old, owner: self)
+					}
+					claimedCameraIds = [device.uniqueID]
+				}
+			}
 			session.beginConfiguration()
 			if videoInput == nil || videoInput?.device.uniqueID != device.uniqueID {
 				do {
@@ -316,6 +354,8 @@ public final class XplatCameraHost: NSObject {
 					videoInput = input
 					if session.canAddInput(input) {
 						session.addInput(input)
+					} else {
+						failure = "unavailable"
 					}
 				} catch {
 					session.commitConfiguration()
@@ -337,7 +377,16 @@ public final class XplatCameraHost: NSObject {
 				self.audioInput = nil
 			}
 
-			if movieOutput == nil {
+			if photo && photoOutput == nil {
+				let output = AVCapturePhotoOutput()
+				if session.canAddOutput(output) {
+					session.addOutput(output)
+					photoOutput = output
+				} else {
+					failure = "unavailable"
+				}
+			}
+			if !photo && movieOutput == nil {
 				let output = AVCaptureMovieFileOutput()
 				if session.canAddOutput(output) {
 					session.addOutput(output)
@@ -394,13 +443,75 @@ public final class XplatCameraHost: NSObject {
 			applyRotation(layer.connection)
 		}
 		queue.async {
-			if !session.isRunning {
+			if !self.disposed && !session.isRunning {
 				session.startRunning()
 			}
 		}
 		return nil
 	}
 
+	/// Stills use AVCapturePhotoOutput, never movie recording or an audio input.
+	@objc public func capturePhoto(_ reply: @escaping (NSData?) -> Void) -> NSString? {
+		guard !disposed, photoDelegate == nil, let photoOutput, session?.isRunning == true else {
+			return "unavailable"
+		}
+		guard photoOutput.availablePhotoCodecTypes.contains(.jpeg) else { return "unavailable" }
+		let delegate = XplatPhotoDelegate()
+		delegate.reply = { [weak self] data in
+			self?.photoDelegate = nil
+			reply(data as NSData?)
+		}
+		photoDelegate = delegate
+		let settings = AVCapturePhotoSettings(format: [AVVideoCodecKey: AVVideoCodecType.jpeg])
+		queue.async { [self] in
+			guard !disposed else { return }
+			photoOutput.capturePhoto(with: settings, delegate: delegate)
+		}
+		return nil
+	}
+
+	/// Meters one autofocus/auto-exposure pass at a normalized preview
+	/// point (0-1, top-left origin as the user sees it). Returns whether
+	/// any metering dimension was applied.
+	@objc public func focusAtPoint(_ options: NSDictionary) -> Bool {
+		guard !disposed, let layer = previewLayer else { return false }
+		let x = (options["x"] as? NSNumber)?.doubleValue ?? 0
+		let y = (options["y"] as? NSNumber)?.doubleValue ?? 0
+		var point = CGPoint(
+			x: min(max(x, 0), 1) * layer.bounds.width,
+			y: min(max(y, 0), 1) * layer.bounds.height
+		)
+		// Unflipped AppKit views are bottom-left origin; the preview
+		// layer's conversion expects the layer's top-left space.
+		if let view = previewView, !view.isFlipped {
+			point.y = layer.bounds.height - point.y
+		}
+		let devicePoint = layer.captureDevicePointConverted(fromLayerPoint: point)
+		var applied = false
+		queue.sync {
+			guard !disposed, let device = videoInput?.device else { return }
+			let focus = device.isFocusPointOfInterestSupported && device.isFocusModeSupported(.autoFocus)
+			let expose = device.isExposurePointOfInterestSupported && device.isExposureModeSupported(.autoExpose)
+			guard focus || expose else { return }
+			do {
+				try device.lockForConfiguration()
+				// Single-shot AF/AE at the point — the AVCam tap-to-focus
+				// convention; the device locks after metering.
+				if focus {
+					device.focusPointOfInterest = devicePoint
+					device.focusMode = .autoFocus
+				}
+				if expose {
+					device.exposurePointOfInterest = devicePoint
+					device.exposureMode = .autoExpose
+				}
+				device.unlockForConfiguration()
+				applied = true
+			} catch {}
+		}
+		return applied
+	}
+
 	@objc public func detachPreview() {
 		previewLayer?.removeFromSuperlayer()
 		previewLayer = nil
@@ -495,19 +606,34 @@ public final class XplatCameraHost: NSObject {
 	@objc public func dispose() {
 		guard !disposed else { return }
 		disposed = true
-		for observer in observers {
-			NotificationCenter.default.removeObserver(observer)
-		}
+		for observer in observers { NotificationCenter.default.removeObserver(observer) }
 		observers = []
-		detachPreview()
-		session = nil
-		videoInput = nil
-		audioInput = nil
-		movieOutput = nil
+		previewLayer?.removeFromSuperlayer()
+		previewLayer = nil
+		previewView = nil
+		photoDelegate?.reply = nil
+		photoDelegate = nil
+		// Keep the session alive until stop completes. Releasing the claim sooner
+		// could admit another host while AVFoundation still holds the hardware.
+		queue.async { [self] in
+			session?.stopRunning()
+			for id in claimedCameraIds { CameraOwnership.release(id, owner: self) }
+			claimedCameraIds = []
+			session = nil
+			videoInput = nil
+			audioInput = nil
+			movieOutput = nil
+			photoOutput = nil
+		}
 		emit = nil
 	}
 
 	deinit {
-		dispose()
+		for observer in observers { NotificationCenter.default.removeObserver(observer) }
+		let stoppedSession = session
+		// Explicit disposal handles claims. A live claim keeps no strong owner;
+		// synchronous fallback only runs if consumers omit disposal.
+		stoppedSession?.stopRunning()
+		for id in claimedCameraIds { CameraOwnership.release(id, owner: self) }
 	}
 }

package/platforms/macos/src/XplatPhotoCaptureSheet.swift

@@ -0,0 +1,192 @@
+import AppKit
+import AVFoundation
+
+/// App-owned still-photo UI. No microphone input, movie output or Photos writes.
+@objc(XplatPhotoCaptureSheet)
+public final class XplatPhotoCaptureSheet: NSObject, NSWindowDelegate {
+	private let host = XplatCameraHost()
+	private let lifecycle = PhotoCaptureLifecycle()
+	private var sheet: NSWindow?
+	private weak var parent: NSWindow?
+	private var reply: ((String?) -> Void)?
+	private var timeout: DispatchWorkItem?
+	private var closeObserver: NSObjectProtocol?
+	private var preview: NSView?
+	private var captureButton: NSButton?
+	private var statusLabel: NSTextField?
+	private var options: NSDictionary = [:]
+	private var disposed = false
+	var operationTimeout: TimeInterval = 15
+
+	@objc public func permissionStatus() -> NSString { host.permissionStatus("camera") }
+
+	@objc public func present(_ options: NSDictionary, reply: @escaping (String?) -> Void) {
+		guard let parent = NSApp.keyWindow ?? NSApp.mainWindow else { reply(nil); return }
+		presentOnWindow(parent, options: options, reply: reply)
+	}
+
+	// Explicit host window also allows deterministic AppKit lifecycle checks.
+	func presentOnWindow(_ parent: NSWindow, options: NSDictionary, reply: @escaping (String?) -> Void) {
+		guard !disposed, sheet == nil, parent.attachedSheet == nil,
+			!(options["saveToGallery"] as? Bool ?? false)
+		else { reply(nil); return }
+		self.options = options
+		self.reply = reply
+		self.parent = parent
+		let sheet = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 640, height: 480),
+			styleMask: [.titled, .closable], backing: .buffered, defer: false)
+		sheet.title = "Take a photo"
+		sheet.delegate = self
+		let content = NSView(frame: NSRect(x: 0, y: 0, width: 640, height: 480))
+		let preview = NSView(frame: NSRect(x: 16, y: 80, width: 608, height: 384))
+		preview.wantsLayer = true
+		preview.layer?.backgroundColor = NSColor.black.cgColor
+		content.addSubview(preview)
+		let status = NSTextField(labelWithString: "Choose Capture to start the camera.")
+		status.frame = NSRect(x: 16, y: 48, width: 440, height: 22)
+		content.addSubview(status)
+		let cancel = NSButton(title: "Cancel", target: self, action: #selector(cancelPhoto))
+		cancel.keyEquivalent = "\u{1b}"
+		cancel.frame = NSRect(x: 432, y: 12, width: 92, height: 32)
+		content.addSubview(cancel)
+		let capture = NSButton(title: "Capture", target: self, action: #selector(capturePhoto))
+		capture.keyEquivalent = "\r"
+		capture.frame = NSRect(x: 528, y: 12, width: 96, height: 32)
+		content.addSubview(capture)
+		sheet.contentView = content
+		self.sheet = sheet
+		self.preview = preview
+		statusLabel = status
+		captureButton = capture
+		closeObserver = NotificationCenter.default.addObserver(forName: NSWindow.willCloseNotification,
+			object: parent, queue: .main) { [weak self] _ in self?.complete(nil) }
+		parent.beginSheet(sheet) { [weak self] _ in self?.complete(nil) }
+	}
+
+	private func deadline(_ token: Int) {
+		timeout?.cancel()
+		let work = DispatchWorkItem { [weak self] in
+			guard let self, lifecycle.accepts(token) else { return }
+			complete(nil)
+		}
+		timeout = work
+		DispatchQueue.main.asyncAfter(deadline: .now() + operationTimeout, execute: work)
+	}
+
+	@objc private func capturePhoto() {
+		if let token = lifecycle.prepare() {
+			captureButton?.isEnabled = false
+			statusLabel?.stringValue = "Starting camera…"
+			deadline(token)
+			// Authorization happens only after the user presses Capture.
+			host.requestPermission("camera") { [weak self] status in
+				guard let self, lifecycle.accepts(token) else { return }
+				guard status == "granted" else { complete(nil); return }
+				DispatchQueue.global(qos: .userInitiated).async { [self] in
+					let failure = self.host.configure(["photo": true, "audio": false])
+					DispatchQueue.main.async { [self] in
+						guard self.lifecycle.accepts(token) else { return }
+						guard failure == nil, let preview = self.preview else { self.complete(nil); return }
+						self.host.installObserver { [weak self] message in
+							guard let self, lifecycle.accepts(token),
+								let data = message.data(using: .utf8),
+								let event = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+							else { return }
+							if event["type"] as? String == "previewReady", event["ready"] as? Bool == true,
+								lifecycle.ready(token) {
+								timeout?.cancel()
+								captureButton?.isEnabled = true
+								statusLabel?.stringValue = "Frame your photo, then choose Capture."
+							} else if event["type"] as? String == "interrupted" ||
+								(event["type"] as? String == "availability" && event["available"] as? Bool == false) {
+								complete(nil)
+							}
+						}
+						if self.host.attachPreview(preview) != nil { self.complete(nil) }
+					}
+				}
+			}
+			return
+		}
+		guard let token = lifecycle.capture() else { return }
+		captureButton?.isEnabled = false
+		statusLabel?.stringValue = "Taking photo…"
+		deadline(token)
+		if host.capturePhoto({ [weak self] data in
+			guard let self, lifecycle.accepts(token) else { return }
+			guard let data, let result = persist(data as Data) else { complete(nil); return }
+			complete(result)
+		}) != nil { complete(nil) }
+	}
+
+	private func persist(_ data: Data) -> String? {
+		guard let source = NSBitmapImageRep(data: data) else { return nil }
+		let width = (options["width"] as? NSNumber)?.doubleValue ?? Double(source.pixelsWide)
+		let height = (options["height"] as? NSNumber)?.doubleValue ?? Double(source.pixelsHigh)
+		guard width.isFinite, height.isFinite, width >= 1, height >= 1, width <= 16384, height <= 16384, width * height <= 64_000_000 else { return nil }
+		let keepAspectRatio = options["keepAspectRatio"] as? Bool ?? true
+		let scale = min(width / Double(source.pixelsWide), height / Double(source.pixelsHigh), 1)
+		let size = NSSize(width: keepAspectRatio ? Double(source.pixelsWide) * scale : width,
+			height: keepAspectRatio ? Double(source.pixelsHigh) * scale : height)
+		guard let bitmap = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: Int(size.width),
+			pixelsHigh: Int(size.height), bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true,
+			isPlanar: false, colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0),
+			let context = NSGraphicsContext(bitmapImageRep: bitmap) else { return nil }
+		NSGraphicsContext.saveGraphicsState()
+		NSGraphicsContext.current = context
+		let image = NSImage(size: NSSize(width: source.pixelsWide, height: source.pixelsHigh))
+		image.addRepresentation(source)
+		image.draw(in: NSRect(origin: .zero, size: size))
+		NSGraphicsContext.restoreGraphicsState()
+		guard let jpeg = bitmap.representation(using: .jpeg, properties: [.compressionFactor: 0.9]) else { return nil }
+		let name = "octane-capture-\(UUID().uuidString).jpg"
+		let url = FileManager.default.temporaryDirectory.appendingPathComponent(name)
+		do {
+			let payload: [String: String] = ["name": name, "uri": url.path,
+				"dataUrl": "data:image/jpeg;base64," + jpeg.base64EncodedString()]
+			let message = try JSONSerialization.data(withJSONObject: payload)
+			try jpeg.write(to: url, options: .atomic)
+			return String(data: message, encoding: .utf8)
+		} catch {
+			try? FileManager.default.removeItem(at: url)
+			return nil
+		}
+	}
+
+	@objc private func cancelPhoto() { complete(nil) }
+	public func windowShouldClose(_ sender: NSWindow) -> Bool { complete(nil); return false }
+
+	private func complete(_ result: String?) {
+		guard lifecycle.finish() else { return }
+		let callback = reply
+		reply = nil
+		dispose()
+		callback?(result)
+	}
+
+	@objc public func discard(_ path: String) {
+		let url = URL(fileURLWithPath: path).standardizedFileURL
+		guard url.deletingLastPathComponent() == FileManager.default.temporaryDirectory.standardizedFileURL,
+			url.lastPathComponent.hasPrefix("octane-capture-") else { return }
+		try? FileManager.default.removeItem(at: url)
+	}
+
+	@objc public func dispose() {
+		guard !disposed else { return }
+		disposed = true
+		timeout?.cancel()
+		timeout = nil
+		if let closeObserver { NotificationCenter.default.removeObserver(closeObserver) }
+		closeObserver = nil
+		host.dispose()
+		if let sheet { parent?.endSheet(sheet); sheet.orderOut(nil) }
+		sheet = nil
+		preview = nil
+		captureButton = nil
+		statusLabel = nil
+		// Disposal is also a cancellation, including an external owner teardown.
+		if lifecycle.finish() { let callback = reply; reply = nil; callback?(nil) }
+	}
+
+	deinit { dispose() }
+}