@ume-group/contracts 0.2.1

package/dist/webcam/WebcamStreamManager.js

@@ -0,0 +1,356 @@
+/**
+ * WebcamStreamManager — Framework-agnostic webcam stream management.
+ *
+ * Extracted from editor/player WebcamCapture.svelte to eliminate code duplication.
+ * Both Svelte components become thin wrappers around this class.
+ *
+ * Handles:
+ * - Device enumeration (video + audio, with Windows role-prefix filtering)
+ * - getUserMedia with OverconstrainedError fallback
+ * - Orientation-aware aspect ratio (always landscape for 3D viewport)
+ * - Track death auto-restart (Android Chrome rotation)
+ * - devicechange listener for hot-plug
+ */
+/** Video constraints for webcam capture */
+const VIDEO_CONSTRAINTS_BASE = {
+    width: { ideal: 1280, max: 1920 },
+    height: { ideal: 720, max: 1080 },
+    frameRate: { ideal: 30, max: 60 }
+};
+/** Windows audio endpoint role prefixes (duplicates from same physical device) */
+const WINDOWS_ROLE_PREFIXES = /^(Standard|Default|Kommunikasjon|Communications)\s*-\s*/i;
+/**
+ * Deduplicate Windows devices by cleaned label.
+ * Windows lists each physical device multiple times with role prefixes
+ * (e.g., "Standard - Bose", "Communications - Bose") and different deviceIds
+ * per role. Some Bluetooth devices ONLY appear with a prefix.
+ * Strip prefixes, deduplicate by cleaned label, keep the first entry.
+ */
+function deduplicateDevices(devices) {
+    const seen = new Set();
+    const result = [];
+    for (const d of devices) {
+        const cleanLabel = d.label.replace(WINDOWS_ROLE_PREFIXES, '');
+        if (seen.has(cleanLabel))
+            continue;
+        seen.add(cleanLabel);
+        if (cleanLabel === d.label) {
+            result.push(d);
+        }
+        else {
+            // MediaDeviceInfo is read-only — wrap with clean label
+            result.push(Object.defineProperty(Object.create(d, {
+                deviceId: { value: d.deviceId, enumerable: true },
+                groupId: { value: d.groupId, enumerable: true },
+                kind: { value: d.kind, enumerable: true },
+                toJSON: { value: () => d.toJSON() },
+            }), 'label', { value: cleanLabel, enumerable: true }));
+        }
+    }
+    return result;
+}
+export class WebcamStreamManager {
+    callbacks;
+    videoElement = null;
+    currentStream = null;
+    isLoading = false;
+    videoReadyNotified = false;
+    nativeVideoWidth = 0;
+    nativeVideoHeight = 0;
+    isAutoRestarting = false;
+    isDestroyed = false;
+    // Bound listener references for cleanup
+    boundDeviceChange;
+    boundOrientationChange;
+    constructor(callbacks = {}) {
+        this.callbacks = callbacks;
+        this.boundDeviceChange = () => this.enumerateDevices();
+        this.boundOrientationChange = () => this.handleOrientationChange();
+    }
+    /** Check if webcam API is available (requires secure context) */
+    isWebcamApiAvailable() {
+        return !!(navigator.mediaDevices && navigator.mediaDevices.getUserMedia);
+    }
+    /** Get current device orientation */
+    getCurrentOrientation() {
+        if (screen.orientation) {
+            return screen.orientation.type.startsWith('portrait') ? 'portrait' : 'landscape';
+        }
+        return window.innerHeight > window.innerWidth ? 'portrait' : 'landscape';
+    }
+    /**
+     * Calculate effective aspect ratio for the webcam plane.
+     * Always returns landscape (>= 1.0) — the 3D viewport maintains
+     * the video content's aspect ratio regardless of device orientation.
+     */
+    getEffectiveAspectRatio() {
+        if (this.nativeVideoWidth === 0 || this.nativeVideoHeight === 0) {
+            return 16 / 9;
+        }
+        return Math.max(this.nativeVideoWidth, this.nativeVideoHeight) /
+            Math.min(this.nativeVideoWidth, this.nativeVideoHeight);
+    }
+    /** Handle orientation change — recalculate and report new effective aspect ratio */
+    handleOrientationChange() {
+        if (this.currentStream && this.videoElement && this.nativeVideoWidth > 0) {
+            const effectiveAspect = this.getEffectiveAspectRatio();
+            const effectiveWidth = Math.max(this.nativeVideoWidth, this.nativeVideoHeight);
+            const effectiveHeight = Math.min(this.nativeVideoWidth, this.nativeVideoHeight);
+            this.callbacks.onDimensionsReady?.(effectiveWidth, effectiveHeight, effectiveAspect);
+        }
+    }
+    /**
+     * Wait for video element to be ready for playback.
+     * Resolves immediately if already ready, otherwise waits for canplay event.
+     */
+    waitForVideoReady(video) {
+        return new Promise((resolve, reject) => {
+            const onCanPlay = () => {
+                video.removeEventListener('canplay', onCanPlay);
+                video.removeEventListener('error', onErr);
+                resolve();
+            };
+            const onErr = () => {
+                video.removeEventListener('canplay', onCanPlay);
+                video.removeEventListener('error', onErr);
+                reject(new Error('Video element failed to load'));
+            };
+            if (video.readyState >= 3) {
+                resolve();
+            }
+            else {
+                video.addEventListener('canplay', onCanPlay);
+                video.addEventListener('error', onErr);
+            }
+        });
+    }
+    /**
+     * Attach a stream to the video element, wait for readiness, and notify callbacks.
+     * Shared by the primary path and the OverconstrainedError fallback.
+     */
+    async attachStream(stream, deviceId) {
+        this.currentStream = stream;
+        // Monitor tracks for unexpected death (Android Chrome kills tracks on rotation)
+        stream.getTracks().forEach((track) => {
+            track.addEventListener('ended', () => {
+                if (!this.isDestroyed && !this.isAutoRestarting && !this.isLoading) {
+                    this.isAutoRestarting = true;
+                    setTimeout(() => {
+                        this.isAutoRestarting = false;
+                        if (!this.isDestroyed) {
+                            this.startStream(deviceId);
+                        }
+                    }, 500);
+                }
+            });
+        });
+        if (this.videoElement) {
+            this.videoElement.srcObject = stream;
+            await this.waitForVideoReady(this.videoElement);
+            await this.videoElement.play();
+            this.notifyVideoReady(this.videoElement);
+        }
+        this.callbacks.onStreamStart?.(stream);
+    }
+    /**
+     * After stream is attached and video is playing, extract dimensions
+     * and notify callbacks.
+     */
+    notifyVideoReady(video) {
+        this.nativeVideoWidth = video.videoWidth;
+        this.nativeVideoHeight = video.videoHeight;
+        this.getCurrentOrientation(); // capture initial orientation
+        const effectiveAspect = this.getEffectiveAspectRatio();
+        if (!this.videoReadyNotified) {
+            this.videoReadyNotified = true;
+            this.callbacks.onVideoReady?.(video);
+            const effectiveWidth = Math.max(this.nativeVideoWidth, this.nativeVideoHeight);
+            const effectiveHeight = Math.min(this.nativeVideoWidth, this.nativeVideoHeight);
+            this.callbacks.onDimensionsReady?.(effectiveWidth, effectiveHeight, effectiveAspect);
+        }
+    }
+    /**
+     * Enumerate available video and audio devices.
+     *
+     * Never calls getUserMedia({ audio: true }) — that triggers Windows
+     * communication mode. Chrome grants labeled audio devices when camera
+     * permission alone is given.
+     */
+    async enumerateDevices() {
+        if (!this.isWebcamApiAvailable()) {
+            const message = 'Webcam requires HTTPS. Please use HTTPS or localhost.';
+            console.warn('[WebcamStreamManager]', message);
+            this.callbacks.onError?.(message);
+            this.callbacks.onDevicesEnumerated?.([]);
+            return [];
+        }
+        try {
+            let devices = await navigator.mediaDevices.enumerateDevices();
+            const hasLabels = devices.some((d) => d.kind === 'videoinput' && d.label);
+            if (!hasLabels) {
+                const permissionStream = await navigator.mediaDevices.getUserMedia({ video: true });
+                permissionStream.getTracks().forEach((track) => track.stop());
+                devices = await navigator.mediaDevices.enumerateDevices();
+            }
+            const videoDevices = deduplicateDevices(devices.filter((d) => d.kind === 'videoinput'));
+            const audioDevices = deduplicateDevices(devices.filter((d) => d.kind === 'audioinput'));
+            this.callbacks.onDevicesEnumerated?.(videoDevices);
+            this.callbacks.onAudioDevicesEnumerated?.(audioDevices);
+            return videoDevices;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to enumerate devices';
+            console.error('Failed to enumerate webcam devices:', err);
+            this.callbacks.onError?.(message);
+            return [];
+        }
+    }
+    /**
+     * Start the webcam stream.
+     * @param deviceId - Specific camera device ID, or undefined for default front camera
+     */
+    async startStream(deviceId) {
+        if (this.isLoading || this.isDestroyed)
+            return;
+        if (!this.videoElement)
+            return;
+        if (!this.isWebcamApiAvailable()) {
+            const message = 'Webcam requires HTTPS. Please use HTTPS or localhost.';
+            this.callbacks.onError?.(message);
+            return;
+        }
+        this.isLoading = true;
+        try {
+            // Stop any existing stream (silent = don't trigger callbacks during restart)
+            this.stopStream(true);
+            // Build constraints — don't combine facingMode with deviceId (OverconstrainedError)
+            const videoConstraints = deviceId
+                ? { ...VIDEO_CONSTRAINTS_BASE, deviceId: { exact: deviceId } }
+                : { ...VIDEO_CONSTRAINTS_BASE, facingMode: 'user' };
+            const stream = await navigator.mediaDevices.getUserMedia({
+                video: videoConstraints,
+                audio: false
+            });
+            if (this.isDestroyed) {
+                stream.getTracks().forEach((t) => t.stop());
+                return;
+            }
+            await this.attachStream(stream, deviceId);
+        }
+        catch (err) {
+            // OverconstrainedError fallback — retry with default camera
+            if (deviceId && err instanceof DOMException && err.name === 'OverconstrainedError') {
+                console.warn('Requested deviceId not available, falling back to default camera');
+                try {
+                    this.stopStream(true);
+                    const stream = await navigator.mediaDevices.getUserMedia({
+                        video: { ...VIDEO_CONSTRAINTS_BASE, facingMode: 'user' },
+                        audio: false
+                    });
+                    if (this.isDestroyed) {
+                        stream.getTracks().forEach((t) => t.stop());
+                        return;
+                    }
+                    await this.attachStream(stream);
+                    return;
+                }
+                catch (fallbackErr) {
+                    console.error('Fallback camera also failed:', fallbackErr);
+                }
+            }
+            const message = this.getErrorMessage(err);
+            console.error('Failed to start webcam:', err);
+            this.callbacks.onError?.(message);
+        }
+        finally {
+            this.isLoading = false;
+        }
+    }
+    /** Map DOMException names to user-friendly error messages */
+    getErrorMessage(err) {
+        if (err instanceof DOMException) {
+            switch (err.name) {
+                case 'NotAllowedError':
+                    return 'Camera permission denied. Please allow camera access.';
+                case 'NotFoundError':
+                    return 'No camera found. Please connect a webcam.';
+                case 'NotReadableError':
+                    return 'Camera is in use. Close the webcam in any other Includu tabs or applications, then try again.';
+                case 'OverconstrainedError':
+                    return 'Camera does not support the requested settings.';
+                default:
+                    return `Camera error: ${err.message}`;
+            }
+        }
+        if (err instanceof Error)
+            return err.message;
+        return 'Failed to start webcam';
+    }
+    /**
+     * Stop the webcam stream.
+     * @param silent - If true, don't call onStreamStop callback (used during restart)
+     */
+    stopStream(silent = false) {
+        if (!this.currentStream)
+            return;
+        this.currentStream.getTracks().forEach((track) => track.stop());
+        this.currentStream = null;
+        this.videoReadyNotified = false;
+        this.nativeVideoWidth = 0;
+        this.nativeVideoHeight = 0;
+        if (this.videoElement) {
+            this.videoElement.srcObject = null;
+        }
+        if (!silent) {
+            this.callbacks.onStreamStop?.();
+        }
+    }
+    /** Whether a stream is currently active */
+    get hasStream() {
+        return this.currentStream !== null;
+    }
+    /** Whether the manager is currently starting a stream */
+    get loading() {
+        return this.isLoading;
+    }
+    /**
+     * Bind to a video element. Call this once after the element is created.
+     * The video element is used as the srcObject target for the stream.
+     */
+    setVideoElement(el) {
+        this.videoElement = el;
+    }
+    /**
+     * Initialize event listeners. Call on mount.
+     * Enumerates devices and starts listening for device/orientation changes.
+     */
+    init() {
+        this.enumerateDevices();
+        navigator.mediaDevices.addEventListener('devicechange', this.boundDeviceChange);
+        if (screen.orientation) {
+            screen.orientation.addEventListener('change', this.boundOrientationChange);
+        }
+        else {
+            window.addEventListener('orientationchange', this.boundOrientationChange);
+        }
+        window.addEventListener('resize', this.boundOrientationChange);
+    }
+    /**
+     * Clean up all resources. Call on unmount.
+     * @param persistStream - If true, don't stop the stream (parent will manage it)
+     */
+    destroy(persistStream = false) {
+        this.isDestroyed = true;
+        if (!persistStream) {
+            this.stopStream();
+        }
+        navigator.mediaDevices.removeEventListener('devicechange', this.boundDeviceChange);
+        if (screen.orientation) {
+            screen.orientation.removeEventListener('change', this.boundOrientationChange);
+        }
+        else {
+            window.removeEventListener('orientationchange', this.boundOrientationChange);
+        }
+        window.removeEventListener('resize', this.boundOrientationChange);
+    }
+}

package/dist/webcam/index.d.ts

@@ -0,0 +1,5 @@
+export { WebcamStreamManager } from './WebcamStreamManager.js';
+export type { WebcamStreamCallbacks } from './WebcamStreamManager.js';
+export { GarbageMatteDragManager } from './GarbageMatteDragManager.js';
+export type { DragHandle, GarbageMatteDragCallbacks, GarbageMatteDragConfig } from './GarbageMatteDragManager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/webcam/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webcam/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,YAAY,EAAE,UAAU,EAAE,yBAAyB,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/webcam/index.js

@@ -0,0 +1,2 @@
+export { WebcamStreamManager } from './WebcamStreamManager.js';
+export { GarbageMatteDragManager } from './GarbageMatteDragManager.js';