@ume-group/contracts 0.2.1

package/dist/webcam/GarbageMatteDragManager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * GarbageMatteDragManager — Framework-agnostic garbage matte drag logic.
+ *
+ * Extracted from editor/player GarbageMatteOverlay.svelte to eliminate
+ * code duplication. Both Svelte components become thin wrappers.
+ *
+ * Handles:
+ * - Drag state management (start, move, end)
+ * - UV-space coordinate calculation from pointer events
+ * - Rectangle corner/edge/move handle clamping
+ * - Window-level pointermove/pointerup listeners
+ */
+import type { RectangleGarbageMatte } from '../layer2.js';
+/** Handle types for drag interaction */
+export type DragHandle = 'tl' | 'tr' | 'bl' | 'br' | 't' | 'r' | 'b' | 'l' | 'move';
+export interface GarbageMatteDragCallbacks {
+    /** Called on every drag move with the updated rectangle */
+    onRectangleChange: (rect: RectangleGarbageMatte) => void;
+    /** Called when drag starts (e.g., beginBatch for undo) */
+    onDragStart?: () => void;
+    /** Called when drag ends normally (e.g., endBatch + save to project) */
+    onDragEnd?: () => void;
+    /** Called when drag is cancelled by the system (e.g., cancelBatch to revert). Falls back to onDragEnd if not provided. */
+    onDragCancel?: () => void;
+}
+export interface GarbageMatteDragConfig {
+    /** Reference to the overlay element for getBoundingClientRect */
+    getOverlayElement: () => HTMLElement | null;
+    /** Webcam aspect ratio for correct UV mapping */
+    getWebcamAspectRatio: () => number;
+    /** Current rectangle state for drag start snapshot */
+    getCurrentRectangle: () => RectangleGarbageMatte;
+}
+export declare class GarbageMatteDragManager {
+    private callbacks;
+    private config;
+    private dragState;
+    private boundMove;
+    private boundUp;
+    constructor(callbacks: GarbageMatteDragCallbacks, config: GarbageMatteDragConfig);
+    /** Whether a drag is currently in progress */
+    get isDragging(): boolean;
+    /**
+     * Start a drag operation. Call from pointerdown on a handle element.
+     * Automatically calls preventDefault/stopPropagation on the event.
+     */
+    startDrag(e: PointerEvent, handle: DragHandle): void;
+    private handlePointerMove;
+    private handlePointerUp;
+    /**
+     * Compute new rectangle from drag delta, applying handle-specific constraints.
+     * Pure function — no side effects.
+     */
+    private computeNewRect;
+    /**
+     * Move a handle by a UV-space delta. For keyboard-driven adjustments.
+     * Reads the current rectangle, computes the new position, and fires onRectangleChange.
+     */
+    moveHandle(handle: DragHandle, deltaX: number, deltaY: number): void;
+    /** Clean up window listeners if component unmounts during drag */
+    destroy(): void;
+}
+//# sourceMappingURL=GarbageMatteDragManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GarbageMatteDragManager.d.ts","sourceRoot":"","sources":["../../src/webcam/GarbageMatteDragManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE1D,wCAAwC;AACxC,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,MAAM,CAAC;AAUpF,MAAM,WAAW,yBAAyB;IACzC,2DAA2D;IAC3D,iBAAiB,EAAE,CAAC,IAAI,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACzD,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,0HAA0H;IAC1H,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACtC,iEAAiE;IACjE,iBAAiB,EAAE,MAAM,WAAW,GAAG,IAAI,CAAC;IAC5C,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,MAAM,CAAC;IACnC,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;CACjD;AAKD,qBAAa,uBAAuB;IAMlC,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IANf,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,OAAO,CAA4B;gBAGlC,SAAS,EAAE,yBAAyB,EACpC,MAAM,EAAE,sBAAsB;IAMvC,8CAA8C;IAC9C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAuBpD,OAAO,CAAC,iBAAiB;IAsBzB,OAAO,CAAC,eAAe;IAevB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAkFtB;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAMpE,kEAAkE;IAClE,OAAO,IAAI,IAAI;CAQf"}

package/dist/webcam/GarbageMatteDragManager.js

@@ -0,0 +1,183 @@
+/**
+ * GarbageMatteDragManager — Framework-agnostic garbage matte drag logic.
+ *
+ * Extracted from editor/player GarbageMatteOverlay.svelte to eliminate
+ * code duplication. Both Svelte components become thin wrappers.
+ *
+ * Handles:
+ * - Drag state management (start, move, end)
+ * - UV-space coordinate calculation from pointer events
+ * - Rectangle corner/edge/move handle clamping
+ * - Window-level pointermove/pointerup listeners
+ */
+/** Minimum size constraint (5% of UV space) to prevent zero-size rectangles */
+const MIN_SIZE = 0.05;
+export class GarbageMatteDragManager {
+    callbacks;
+    config;
+    dragState = null;
+    boundMove;
+    boundUp;
+    constructor(callbacks, config) {
+        this.callbacks = callbacks;
+        this.config = config;
+        this.boundMove = (e) => this.handlePointerMove(e);
+        this.boundUp = (e) => this.handlePointerUp(e);
+    }
+    /** Whether a drag is currently in progress */
+    get isDragging() {
+        return this.dragState?.active ?? false;
+    }
+    /**
+     * Start a drag operation. Call from pointerdown on a handle element.
+     * Automatically calls preventDefault/stopPropagation on the event.
+     */
+    startDrag(e, handle) {
+        e.preventDefault();
+        e.stopPropagation();
+        this.callbacks.onDragStart?.();
+        const rect = this.config.getCurrentRectangle();
+        this.dragState = {
+            active: true,
+            handle,
+            startX: e.clientX,
+            startY: e.clientY,
+            startRect: {
+                topLeft: { ...rect.topLeft },
+                bottomRight: { ...rect.bottomRight }
+            }
+        };
+        window.addEventListener('pointermove', this.boundMove);
+        window.addEventListener('pointerup', this.boundUp);
+        window.addEventListener('pointercancel', this.boundUp);
+    }
+    handlePointerMove(e) {
+        if (!this.dragState?.active)
+            return;
+        const overlayEl = this.config.getOverlayElement();
+        if (!overlayEl)
+            return;
+        // Get actual rendered dimensions via getBoundingClientRect
+        const rect = overlayEl.getBoundingClientRect();
+        const actualHeight = rect.height;
+        // Use the webcam plane's pixel width for correct UV mapping
+        const actualPlaneWidth = actualHeight * this.config.getWebcamAspectRatio();
+        // Calculate delta in UV space (0-1) using the plane's actual dimensions
+        // UV coordinates are in texture space (not visual/mirrored space)
+        // The shader handles visual mirroring separately
+        const deltaX = (e.clientX - this.dragState.startX) / actualPlaneWidth;
+        const deltaY = (e.clientY - this.dragState.startY) / actualHeight;
+        const newRect = this.computeNewRect(this.dragState.handle, this.dragState.startRect, deltaX, deltaY);
+        this.callbacks.onRectangleChange(newRect);
+    }
+    handlePointerUp(e) {
+        if (!this.dragState?.active)
+            return;
+        window.removeEventListener('pointermove', this.boundMove);
+        window.removeEventListener('pointerup', this.boundUp);
+        window.removeEventListener('pointercancel', this.boundUp);
+        if (e.type === 'pointercancel') {
+            (this.callbacks.onDragCancel ?? this.callbacks.onDragEnd)?.();
+        }
+        else {
+            this.callbacks.onDragEnd?.();
+        }
+        this.dragState = null;
+    }
+    /**
+     * Compute new rectangle from drag delta, applying handle-specific constraints.
+     * Pure function — no side effects.
+     */
+    computeNewRect(handle, startRect, deltaX, deltaY) {
+        const newRect = {
+            topLeft: { ...startRect.topLeft },
+            bottomRight: { ...startRect.bottomRight }
+        };
+        switch (handle) {
+            case 'tl':
+                newRect.topLeft = {
+                    x: Math.max(0, Math.min(newRect.bottomRight.x - MIN_SIZE, startRect.topLeft.x + deltaX)),
+                    y: Math.max(0, Math.min(newRect.bottomRight.y - MIN_SIZE, startRect.topLeft.y + deltaY))
+                };
+                break;
+            case 'tr':
+                newRect.topLeft = {
+                    ...newRect.topLeft,
+                    y: Math.max(0, Math.min(newRect.bottomRight.y - MIN_SIZE, startRect.topLeft.y + deltaY))
+                };
+                newRect.bottomRight = {
+                    ...newRect.bottomRight,
+                    x: Math.max(newRect.topLeft.x + MIN_SIZE, Math.min(1, startRect.bottomRight.x + deltaX))
+                };
+                break;
+            case 'bl':
+                newRect.topLeft = {
+                    ...newRect.topLeft,
+                    x: Math.max(0, Math.min(newRect.bottomRight.x - MIN_SIZE, startRect.topLeft.x + deltaX))
+                };
+                newRect.bottomRight = {
+                    ...newRect.bottomRight,
+                    y: Math.max(newRect.topLeft.y + MIN_SIZE, Math.min(1, startRect.bottomRight.y + deltaY))
+                };
+                break;
+            case 'br':
+                newRect.bottomRight = {
+                    x: Math.max(newRect.topLeft.x + MIN_SIZE, Math.min(1, startRect.bottomRight.x + deltaX)),
+                    y: Math.max(newRect.topLeft.y + MIN_SIZE, Math.min(1, startRect.bottomRight.y + deltaY))
+                };
+                break;
+            case 't':
+                newRect.topLeft = {
+                    ...newRect.topLeft,
+                    y: Math.max(0, Math.min(newRect.bottomRight.y - MIN_SIZE, startRect.topLeft.y + deltaY))
+                };
+                break;
+            case 'r':
+                newRect.bottomRight = {
+                    ...newRect.bottomRight,
+                    x: Math.max(newRect.topLeft.x + MIN_SIZE, Math.min(1, startRect.bottomRight.x + deltaX))
+                };
+                break;
+            case 'b':
+                newRect.bottomRight = {
+                    ...newRect.bottomRight,
+                    y: Math.max(newRect.topLeft.y + MIN_SIZE, Math.min(1, startRect.bottomRight.y + deltaY))
+                };
+                break;
+            case 'l':
+                newRect.topLeft = {
+                    ...newRect.topLeft,
+                    x: Math.max(0, Math.min(newRect.bottomRight.x - MIN_SIZE, startRect.topLeft.x + deltaX))
+                };
+                break;
+            case 'move': {
+                const width = startRect.bottomRight.x - startRect.topLeft.x;
+                const height = startRect.bottomRight.y - startRect.topLeft.y;
+                const newX = Math.max(0, Math.min(1 - width, startRect.topLeft.x + deltaX));
+                const newY = Math.max(0, Math.min(1 - height, startRect.topLeft.y + deltaY));
+                newRect.topLeft = { x: newX, y: newY };
+                newRect.bottomRight = { x: newX + width, y: newY + height };
+                break;
+            }
+        }
+        return newRect;
+    }
+    /**
+     * Move a handle by a UV-space delta. For keyboard-driven adjustments.
+     * Reads the current rectangle, computes the new position, and fires onRectangleChange.
+     */
+    moveHandle(handle, deltaX, deltaY) {
+        const rect = this.config.getCurrentRectangle();
+        const newRect = this.computeNewRect(handle, rect, deltaX, deltaY);
+        this.callbacks.onRectangleChange(newRect);
+    }
+    /** Clean up window listeners if component unmounts during drag */
+    destroy() {
+        if (this.dragState?.active) {
+            window.removeEventListener('pointermove', this.boundMove);
+            window.removeEventListener('pointerup', this.boundUp);
+            window.removeEventListener('pointercancel', this.boundUp);
+            this.dragState = null;
+        }
+    }
+}

package/dist/webcam/WebcamStreamManager.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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
+ */
+export interface WebcamStreamCallbacks {
+    onDevicesEnumerated?: (devices: MediaDeviceInfo[]) => void;
+    onAudioDevicesEnumerated?: (devices: MediaDeviceInfo[]) => void;
+    onStreamStart?: (stream: MediaStream) => void;
+    onStreamStop?: () => void;
+    onVideoReady?: (video: HTMLVideoElement) => void;
+    onDimensionsReady?: (width: number, height: number, aspectRatio: number) => void;
+    onError?: (error: string) => void;
+}
+export declare class WebcamStreamManager {
+    private callbacks;
+    private videoElement;
+    private currentStream;
+    private isLoading;
+    private videoReadyNotified;
+    private nativeVideoWidth;
+    private nativeVideoHeight;
+    private isAutoRestarting;
+    private isDestroyed;
+    private boundDeviceChange;
+    private boundOrientationChange;
+    constructor(callbacks?: WebcamStreamCallbacks);
+    /** Check if webcam API is available (requires secure context) */
+    private isWebcamApiAvailable;
+    /** Get current device orientation */
+    private getCurrentOrientation;
+    /**
+     * 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.
+     */
+    private getEffectiveAspectRatio;
+    /** Handle orientation change — recalculate and report new effective aspect ratio */
+    private handleOrientationChange;
+    /**
+     * Wait for video element to be ready for playback.
+     * Resolves immediately if already ready, otherwise waits for canplay event.
+     */
+    private waitForVideoReady;
+    /**
+     * Attach a stream to the video element, wait for readiness, and notify callbacks.
+     * Shared by the primary path and the OverconstrainedError fallback.
+     */
+    private attachStream;
+    /**
+     * After stream is attached and video is playing, extract dimensions
+     * and notify callbacks.
+     */
+    private notifyVideoReady;
+    /**
+     * 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.
+     */
+    enumerateDevices(): Promise<MediaDeviceInfo[]>;
+    /**
+     * Start the webcam stream.
+     * @param deviceId - Specific camera device ID, or undefined for default front camera
+     */
+    startStream(deviceId?: string): Promise<void>;
+    /** Map DOMException names to user-friendly error messages */
+    private getErrorMessage;
+    /**
+     * Stop the webcam stream.
+     * @param silent - If true, don't call onStreamStop callback (used during restart)
+     */
+    stopStream(silent?: boolean): void;
+    /** Whether a stream is currently active */
+    get hasStream(): boolean;
+    /** Whether the manager is currently starting a stream */
+    get loading(): boolean;
+    /**
+     * 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: HTMLVideoElement): void;
+    /**
+     * Initialize event listeners. Call on mount.
+     * Enumerates devices and starts listening for device/orientation changes.
+     */
+    init(): void;
+    /**
+     * Clean up all resources. Call on unmount.
+     * @param persistStream - If true, don't stop the stream (parent will manage it)
+     */
+    destroy(persistStream?: boolean): void;
+}
+//# sourceMappingURL=WebcamStreamManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebcamStreamManager.d.ts","sourceRoot":"","sources":["../../src/webcam/WebcamStreamManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkDH,MAAM,WAAW,qBAAqB;IACrC,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;IAC3D,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,IAAI,CAAC;IAChE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC;IACjF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,qBAAa,mBAAmB;IAcnB,OAAO,CAAC,SAAS;IAb7B,OAAO,CAAC,YAAY,CAAiC;IACrD,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,kBAAkB,CAAS;IACnC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,WAAW,CAAS;IAG5B,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,sBAAsB,CAAa;gBAEvB,SAAS,GAAE,qBAA0B;IAKzD,iEAAiE;IACjE,OAAO,CAAC,oBAAoB;IAI5B,qCAAqC;IACrC,OAAO,CAAC,qBAAqB;IAO7B;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAQ/B,oFAAoF;IACpF,OAAO,CAAC,uBAAuB;IAS/B;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAqBzB;;;OAGG;YACW,YAAY;IA4B1B;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAgBxB;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IAqCpD;;;OAGG;IACG,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA+DnD,6DAA6D;IAC7D,OAAO,CAAC,eAAe;IAmBvB;;;OAGG;IACH,UAAU,CAAC,MAAM,UAAQ,GAAG,IAAI;IAkBhC,2CAA2C;IAC3C,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,yDAAyD;IACzD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;OAGG;IACH,eAAe,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAI3C;;;OAGG;IACH,IAAI,IAAI,IAAI;IAYZ;;;OAGG;IACH,OAAO,CAAC,aAAa,UAAQ,GAAG,IAAI;CAepC"}