@ume-group/contracts 0.2.1

package/dist/layer2.js

@@ -0,0 +1,376 @@
+/**
+ * Layer 2: 3D Composite Types
+ *
+ * Type definitions for the 3D composite layer that enables:
+ * - 3D Space Ads: GAM ad templates positioned in 3D space
+ * - Participation: Webcam composite with chroma keying
+ *
+ * Uses the Gausst coordinate system from Patent US8761580B2
+ */
+export const DEFAULT_CAMERA_SETTINGS = {
+    fov: 60, // Vertical FOV - Gausst default (horizontal ~82°, diagonal ~95°, matches typical phone cameras)
+    position: [0, 1.6, 0], // Gausst: Camera at origin, eye level (1.6m)
+    rotation: [-5, 0, 0], // -5° tilt (slightly downward) — centers webcam plane at [0,0,-3.5] on screen
+    lookAt: [0, 1.6, -10] // Gausst: Looking at negative Z (objects in front of camera)
+};
+export const DEFAULT_AD_3D_PLACEMENT = {
+    position: [0, 1, -3], // Gausst: 3m in front of camera (negative Z), 1m above floor
+    rotation: [0, 0, 0],
+    scale: 1.0,
+    materialType: 'unlit'
+};
+export const DEFAULT_AI_SEGMENTATION_SETTINGS = {
+    model: 'mediapipe',
+    threshold: 0.7, // Higher threshold = tighter person mask, less background bleed
+    edgeBlur: 3, // Balanced for real-time (confidence masks provide natural smoothing)
+    flipHorizontal: true,
+    lowLatency: true, // Default: real-time response prioritized
+    quality: 'fast' // Default: selfie_segmenter for close-up
+};
+export const DEFAULT_HSV_WINDOW_SETTINGS = {
+    enabled: false,
+    minHue: 60, // Yellow-ish green
+    maxHue: 180, // Cyan-ish
+    minSaturation: 0.2,
+    maxSaturation: 1.0,
+    minValue: 0.2,
+    maxValue: 1.0
+};
+export const DEFAULT_CHROMA_KEY_SETTINGS = {
+    color: 'custom',
+    customColor: '#00B140', // Standard chroma key green (slightly darker than pure green for better keying)
+    tolerance: 0.35,
+    spillSuppression: 0.25,
+    edgeSoftness: 0.08
+};
+export const DEFAULT_BACKGROUND_REMOVAL = {
+    method: 'ai', // AI is the default - no green screen needed!
+    aiSettings: DEFAULT_AI_SEGMENTATION_SETTINGS,
+    chromaKeySettings: DEFAULT_CHROMA_KEY_SETTINGS
+};
+export const DEFAULT_COLOR_MATCH_SETTINGS = {
+    brightness: 0,
+    contrast: 0,
+    saturation: 0,
+    temperature: 0
+};
+export const DEFAULT_FEATHER_EDGES = {
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0
+};
+/**
+ * Default garbage matte settings - full frame, no masking.
+ */
+export const DEFAULT_GARBAGE_MATTE_SETTINGS = {
+    mode: 'off',
+    rectangle: {
+        topLeft: { x: 0, y: 0 },
+        bottomRight: { x: 1, y: 1 }
+    },
+    polygons: [],
+    feather: 0,
+    invert: false
+};
+// Default reference height for webcam composite (170cm = average adult height)
+const DEFAULT_REFERENCE_HEIGHT = 170;
+// Silhouette is 85% of plane height
+const DEFAULT_SILHOUETTE_RATIO = 0.85;
+/**
+ * Minimum capture height in cm for generous framing.
+ * The webcam plane is always at least this tall, allowing taller people
+ * to walk into frame without reconfiguration. Background removal
+ * makes the extra space transparent.
+ */
+export const MIN_CAPTURE_HEIGHT_CM = 210;
+export const DEFAULT_WEBCAM_COMPOSITE = {
+    enabled: true,
+    position: [0, 0, -3.5], // Gausst: 3.5m in front of camera (negative Z), feet at floor (Y=0)
+    rotation: [0, 0, 0],
+    // Scale = PLANE HEIGHT in meters (170cm person / 0.85 = 2.0m plane)
+    scale: (DEFAULT_REFERENCE_HEIGHT / 100) / DEFAULT_SILHOUETTE_RATIO,
+    referenceHeight: DEFAULT_REFERENCE_HEIGHT, // 170cm - average adult height
+    framingType: 'full', // Full body by default
+    defaultMethod: 'none' // Position first, then enable background removal
+};
+export const DEFAULT_WEBCAM_RUNTIME_STATE = {
+    deviceId: undefined,
+    audioDeviceId: undefined,
+    method: 'none', // Position first, then enable background removal
+    aiSettings: DEFAULT_AI_SEGMENTATION_SETTINGS,
+    chromaKeySettings: DEFAULT_CHROMA_KEY_SETTINGS,
+    colorCorrection: DEFAULT_COLOR_MATCH_SETTINGS,
+    isActive: false,
+    processingEnabled: false, // No processing until method is changed from 'none'
+    mirrored: true // Default: mirrored (selfie mode) for user-facing cameras
+};
+/**
+ * Create a WebcamRuntimeState initialized from a WebcamComposite template.
+ * Uses the template's defaultMethod, defaultAiSettings, and defaultChromaKeySettings as starting values.
+ */
+export function createRuntimeStateFromTemplate(template) {
+    return {
+        ...DEFAULT_WEBCAM_RUNTIME_STATE,
+        method: template.defaultMethod,
+        aiSettings: {
+            ...DEFAULT_AI_SEGMENTATION_SETTINGS,
+            ...(template.defaultAiSettings ?? {})
+        },
+        chromaKeySettings: {
+            ...DEFAULT_CHROMA_KEY_SETTINGS,
+            ...(template.defaultChromaKeySettings ?? {})
+        }
+    };
+}
+export const DEFAULT_LAYER2_SCENE = {
+    camera: DEFAULT_CAMERA_SETTINGS,
+    ads: [],
+    participation: undefined,
+    advancedSceneJson: undefined
+};
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Generate a unique ID for Layer 2 objects
+ */
+export function generateLayer2Id(prefix) {
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+/**
+ * Create a new 3D ad placement with defaults
+ */
+export function createAd3DPlacement(templateId, startFrame, endFrame, overrides) {
+    return {
+        id: generateLayer2Id('ad3d'),
+        templateId,
+        startFrame,
+        endFrame,
+        // Deep copy arrays to prevent shared reference mutation
+        position: [...DEFAULT_AD_3D_PLACEMENT.position],
+        rotation: [...DEFAULT_AD_3D_PLACEMENT.rotation],
+        scale: DEFAULT_AD_3D_PLACEMENT.scale,
+        materialType: DEFAULT_AD_3D_PLACEMENT.materialType,
+        ...overrides
+    };
+}
+/**
+ * Silhouette occupies 85% of plane height (leaves 15% headroom).
+ * This constant is shared between here and Layer2SceneContent.svelte.
+ */
+const SILHOUETTE_HEIGHT_RATIO = 0.85;
+/**
+ * Create a new webcam composite template with defaults.
+ * Note: This creates only the template data. Runtime state (keying, color)
+ * is created separately using createRuntimeStateFromTemplate().
+ *
+ * Scale represents the PLANE HEIGHT in meters (Gausst coordinate system).
+ * For a 170cm person: scale = 1.70 / 0.85 = 2.0 (plane is 2.0m tall)
+ */
+export function createWebcamComposite(startFrame, endFrame, overrides) {
+    // Calculate scale (plane height in meters) from referenceHeight
+    // Plane height = person height / silhouette ratio (person is 85% of plane)
+    const referenceHeight = overrides?.referenceHeight ?? DEFAULT_WEBCAM_COMPOSITE.referenceHeight;
+    const calculatedScale = (referenceHeight / 100) / SILHOUETTE_HEIGHT_RATIO;
+    // Only use calculated scale if scale is NOT explicitly provided in overrides
+    const finalScale = overrides?.scale !== undefined ? overrides.scale : calculatedScale;
+    return {
+        id: generateLayer2Id('webcam'),
+        startFrame,
+        endFrame,
+        enabled: DEFAULT_WEBCAM_COMPOSITE.enabled,
+        // Deep copy arrays to prevent shared reference mutation
+        position: [...DEFAULT_WEBCAM_COMPOSITE.position],
+        rotation: [...DEFAULT_WEBCAM_COMPOSITE.rotation],
+        referenceHeight: DEFAULT_WEBCAM_COMPOSITE.referenceHeight,
+        framingType: DEFAULT_WEBCAM_COMPOSITE.framingType,
+        defaultMethod: DEFAULT_WEBCAM_COMPOSITE.defaultMethod,
+        ...overrides,
+        // Always apply calculated scale last (unless explicitly overridden)
+        scale: finalScale
+    };
+}
+/**
+ * Check if an ad is visible at a given frame
+ */
+export function isAdVisibleAtFrame(ad, frame) {
+    return frame >= ad.startFrame && frame < ad.endFrame;
+}
+/**
+ * Check if webcam composite is visible at a given frame
+ */
+export function isWebcamVisibleAtFrame(webcam, frame) {
+    if (!webcam || !webcam.enabled)
+        return false;
+    return frame >= webcam.startFrame && frame < webcam.endFrame;
+}
+/**
+ * Get all visible 3D ads at a given frame
+ */
+export function getVisibleAdsAtFrame(scene, frame) {
+    return scene.ads.filter((ad) => isAdVisibleAtFrame(ad, frame));
+}
+/**
+ * Calculate the scale factor for a participant based on their height
+ * relative to the reference height set by the content creator.
+ *
+ * @param referenceHeight - Height in cm that the scene is calibrated for
+ * @param participantHeight - Actual participant height in cm
+ * @returns Scale factor to apply (1.0 = same height as reference)
+ *
+ * @example
+ * // Content creator is 180cm, participant is 160cm
+ * calculateParticipantScale(180, 160) // Returns 0.889 (participant appears shorter)
+ *
+ * // Content creator is 160cm, participant is 180cm
+ * calculateParticipantScale(160, 180) // Returns 1.125 (participant appears taller)
+ */
+export function calculateParticipantScale(referenceHeight, participantHeight) {
+    if (referenceHeight <= 0)
+        return 1.0;
+    return participantHeight / referenceHeight;
+}
+// =============================================================================
+// Multi-Camera Shot Resolution Functions
+// =============================================================================
+/**
+ * Generate a unique ID for shot system objects
+ */
+export function generateShotId(prefix = 'shot') {
+    return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+/**
+ * Find which shot preset is active at a given frame.
+ * Returns null if multicam is disabled or no segment covers this frame.
+ */
+export function getActiveShotPreset(scene, frame) {
+    if (!scene.multicamEnabled || !scene.shotSegments || !scene.shotPresets)
+        return null;
+    const segment = scene.shotSegments.find(seg => frame >= seg.startFrame && frame < seg.endFrame);
+    if (!segment)
+        return null;
+    return scene.shotPresets.find(p => p.id === segment.presetId) ?? null;
+}
+/**
+ * Get the camera settings to use at a given frame.
+ * When multicam is enabled and a shot preset covers this frame, returns that preset's camera.
+ * Otherwise returns the scene's default camera.
+ */
+export function getActiveCamera(scene, frame) {
+    const preset = getActiveShotPreset(scene, frame);
+    return preset?.camera ?? scene.camera ?? DEFAULT_CAMERA_SETTINGS;
+}
+/**
+ * Resolve an ad's transform for the current frame.
+ * If a shot-specific override exists, use it. Otherwise use the ad's default transform.
+ * When multicam is enabled and no shot covers the frame, the ad is hidden.
+ */
+export function getAdTransformAtFrame(ad, scene, frame) {
+    const preset = getActiveShotPreset(scene, frame);
+    if (preset && ad.shotTransforms?.[preset.id]) {
+        return ad.shotTransforms[preset.id];
+    }
+    // Multicam enabled but no shot at this frame — hide
+    if (scene.multicamEnabled && !preset) {
+        return {
+            position: ad.position,
+            rotation: ad.rotation,
+            scale: ad.scale,
+            visible: false
+        };
+    }
+    // Default: use the ad's own transform, always visible
+    return {
+        position: ad.position,
+        rotation: ad.rotation,
+        scale: ad.scale,
+        visible: true
+    };
+}
+/**
+ * Resolve a webcam composite's transform for the current frame.
+ * If a shot-specific override exists, use it. Otherwise use the webcam's default transform.
+ * When multicam is enabled and no shot covers the frame, the webcam is hidden.
+ */
+export function getWebcamTransformAtFrame(webcam, scene, frame) {
+    const preset = getActiveShotPreset(scene, frame);
+    if (preset && webcam.shotTransforms?.[preset.id]) {
+        return webcam.shotTransforms[preset.id];
+    }
+    // Multicam enabled but no shot at this frame — hide
+    if (scene.multicamEnabled && !preset) {
+        return {
+            position: webcam.position,
+            rotation: webcam.rotation,
+            scale: webcam.scale,
+            visible: false
+        };
+    }
+    // Default: use the webcam's own transform, always visible
+    return {
+        position: webcam.position,
+        rotation: webcam.rotation,
+        scale: webcam.scale,
+        visible: true
+    };
+}
+/**
+ * Validate and auto-fix shot segments for overlap and bound issues.
+ *
+ * - Minor overlaps (≤ 2 frames): auto-fixed by snapping earlier segment's endFrame
+ * - Major overlaps (> 2 frames): reported in `overlaps[]` for user resolution
+ * - Invalid bounds (startFrame >= endFrame, startFrame < 0): auto-fixed
+ *
+ * Called at import boundaries (tracking import, Advanced Mode sync, JSON load),
+ * NOT during drag (drag handler already clamps per-frame).
+ */
+export function validateAndFixSegments(segments) {
+    if (segments.length === 0)
+        return { valid: true, segments: [] };
+    // Fix individual segment bounds first
+    const fixed = segments.map((s) => {
+        const correctedStart = Math.max(0, s.startFrame);
+        return {
+            ...s,
+            startFrame: correctedStart,
+            endFrame: Math.max(correctedStart + 1, s.endFrame)
+        };
+    });
+    // Sort by startFrame for overlap detection
+    const sorted = [...fixed].sort((a, b) => a.startFrame - b.startFrame);
+    const overlaps = [];
+    for (let i = 0; i < sorted.length - 1; i++) {
+        const overlapFrames = sorted[i].endFrame - sorted[i + 1].startFrame;
+        if (overlapFrames > 0) {
+            if (overlapFrames <= 2) {
+                // Minor overlap — auto-fix by snapping earlier segment's end
+                sorted[i] = { ...sorted[i], endFrame: sorted[i + 1].startFrame };
+            }
+            else {
+                // Major overlap — report for user resolution
+                overlaps.push({
+                    segA: sorted[i].id,
+                    segB: sorted[i + 1].id,
+                    overlapFrames
+                });
+            }
+        }
+    }
+    return {
+        valid: overlaps.length === 0,
+        segments: sorted,
+        ...(overlaps.length > 0 ? { overlaps } : {})
+    };
+}
+/**
+ * Validate that all segment presetId references point to existing presets.
+ * Returns orphaned segment IDs (presetId not found in presets array).
+ */
+export function validatePresetReferences(segments, presets) {
+    const presetIds = new Set(presets.map((p) => p.id));
+    const orphaned = segments.filter((s) => !presetIds.has(s.presetId)).map((s) => s.id);
+    if (orphaned.length === 0)
+        return { valid: true };
+    return { valid: false, orphanedSegments: orphaned };
+}

package/dist/layer2.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=layer2.test.d.ts.map

package/dist/layer2.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layer2.test.d.ts","sourceRoot":"","sources":["../src/layer2.test.ts"],"names":[],"mappings":""}

package/dist/layer2.test.js

@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { isAdVisibleAtFrame, isWebcamVisibleAtFrame, calculateParticipantScale, createRuntimeStateFromTemplate, DEFAULT_AI_SEGMENTATION_SETTINGS, DEFAULT_CHROMA_KEY_SETTINGS } from './layer2';
+const mockAd = {
+    id: 'test-ad',
+    templateId: 'tpl-1',
+    startFrame: 10,
+    endFrame: 50,
+    position: [0, 1, -3],
+    rotation: [0, 0, 0],
+    scale: 1,
+    materialType: 'unlit'
+};
+const mockWebcam = {
+    id: 'test-webcam',
+    enabled: true,
+    startFrame: 0,
+    endFrame: 100,
+    position: [0, 0, -3.5],
+    rotation: [0, 0, 0],
+    scale: 2.0,
+    referenceHeight: 170,
+    framingType: 'full',
+    defaultMethod: 'chromaKey',
+    defaultChromaKeySettings: {
+        tolerance: 0.5,
+        color: 'green'
+    }
+};
+describe('isAdVisibleAtFrame', () => {
+    it('startFrame is inclusive', () => {
+        expect(isAdVisibleAtFrame(mockAd, 10)).toBe(true);
+    });
+    it('endFrame is exclusive', () => {
+        expect(isAdVisibleAtFrame(mockAd, 50)).toBe(false);
+    });
+});
+describe('isWebcamVisibleAtFrame', () => {
+    it('returns false for undefined webcam', () => {
+        expect(isWebcamVisibleAtFrame(undefined, 5)).toBe(false);
+    });
+    it('returns false for disabled webcam', () => {
+        const disabled = { ...mockWebcam, enabled: false };
+        expect(isWebcamVisibleAtFrame(disabled, 5)).toBe(false);
+    });
+});
+describe('calculateParticipantScale', () => {
+    it('shorter participant returns < 1.0', () => {
+        const scale = calculateParticipantScale(180, 160);
+        expect(scale).toBeCloseTo(0.889, 3);
+    });
+    it('zero reference height returns 1.0', () => {
+        expect(calculateParticipantScale(0, 170)).toBe(1.0);
+    });
+});
+describe('createRuntimeStateFromTemplate', () => {
+    it('propagates defaultMethod and defaultChromaKeySettings', () => {
+        const runtime = createRuntimeStateFromTemplate(mockWebcam);
+        expect(runtime.method).toBe('chromaKey');
+        expect(runtime.chromaKeySettings.tolerance).toBe(0.5);
+        expect(runtime.chromaKeySettings.color).toBe('green');
+        // Non-overridden fields should be defaults
+        expect(runtime.chromaKeySettings.spillSuppression).toBe(DEFAULT_CHROMA_KEY_SETTINGS.spillSuppression);
+        expect(runtime.aiSettings).toEqual(DEFAULT_AI_SEGMENTATION_SETTINGS);
+    });
+});

package/dist/perspective.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Perspective Transform Utilities
+ *
+ * Computes CSS matrix3d() transforms from corner points for
+ * perspective-correct overlay rendering.
+ *
+ * @see https://github.com/uMe-Group/Includu/issues/58
+ */
+import type { CornerPoints } from './index';
+/**
+ * Compute a CSS matrix3d transform from source to destination quad
+ *
+ * This implements the homography calculation to map a unit square
+ * to an arbitrary quadrilateral defined by four corner points.
+ *
+ * @param srcWidth - Source element width in pixels
+ * @param srcHeight - Source element height in pixels
+ * @param corners - Destination corner points (normalized 0-1)
+ * @param containerWidth - Container width in pixels
+ * @param containerHeight - Container height in pixels
+ * @returns CSS matrix3d() string or null if no transform needed
+ */
+export declare function computeMatrix3d(srcWidth: number, srcHeight: number, corners: CornerPoints, containerWidth: number, containerHeight: number): string | null;
+/**
+ * Check if corners form a valid (non-degenerate) quadrilateral
+ */
+export declare function isValidQuad(corners: CornerPoints): boolean;
+//# sourceMappingURL=perspective.d.ts.map

package/dist/perspective.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perspective.d.ts","sourceRoot":"","sources":["../src/perspective.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,YAAY,EACrB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,MAAM,GACrB,MAAM,GAAG,IAAI,CA8Cf;AAuFD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAiC1D"}

package/dist/perspective.js

@@ -0,0 +1,157 @@
+/**
+ * Perspective Transform Utilities
+ *
+ * Computes CSS matrix3d() transforms from corner points for
+ * perspective-correct overlay rendering.
+ *
+ * @see https://github.com/uMe-Group/Includu/issues/58
+ */
+/**
+ * Compute a CSS matrix3d transform from source to destination quad
+ *
+ * This implements the homography calculation to map a unit square
+ * to an arbitrary quadrilateral defined by four corner points.
+ *
+ * @param srcWidth - Source element width in pixels
+ * @param srcHeight - Source element height in pixels
+ * @param corners - Destination corner points (normalized 0-1)
+ * @param containerWidth - Container width in pixels
+ * @param containerHeight - Container height in pixels
+ * @returns CSS matrix3d() string or null if no transform needed
+ */
+export function computeMatrix3d(srcWidth, srcHeight, corners, containerWidth, containerHeight) {
+    // Convert normalized corners to pixel positions
+    const dst = {
+        tl: { x: corners.tl.x * containerWidth, y: corners.tl.y * containerHeight },
+        tr: { x: corners.tr.x * containerWidth, y: corners.tr.y * containerHeight },
+        br: { x: corners.br.x * containerWidth, y: corners.br.y * containerHeight },
+        bl: { x: corners.bl.x * containerWidth, y: corners.bl.y * containerHeight }
+    };
+    // Source corners (element at origin with given dimensions)
+    const src = {
+        tl: { x: 0, y: 0 },
+        tr: { x: srcWidth, y: 0 },
+        br: { x: srcWidth, y: srcHeight },
+        bl: { x: 0, y: srcHeight }
+    };
+    // Compute the 3x3 homography matrix
+    // Using the adjugate method for 2D perspective transform
+    const matrix = computeHomography(src.tl.x, src.tl.y, src.tr.x, src.tr.y, src.br.x, src.br.y, src.bl.x, src.bl.y, dst.tl.x, dst.tl.y, dst.tr.x, dst.tr.y, dst.br.x, dst.br.y, dst.bl.x, dst.bl.y);
+    if (!matrix)
+        return null;
+    // Convert 3x3 homography to 4x4 matrix for CSS matrix3d
+    // CSS matrix3d expects column-major order:
+    // matrix3d(a1, a2, a3, a4, b1, b2, b3, b4, c1, c2, c3, c4, d1, d2, d3, d4)
+    const [h11, h12, h13, h21, h22, h23, h31, h32, h33] = matrix;
+    // 3x3 to 4x4 embedding (z = 0 plane)
+    const m3d = [
+        h11, h21, 0, h31,
+        h12, h22, 0, h32,
+        0, 0, 1, 0,
+        h13, h23, 0, h33
+    ];
+    return `matrix3d(${m3d.join(', ')})`;
+}
+/**
+ * Compute 3x3 homography matrix that maps one quad to another
+ *
+ * Uses the Direct Linear Transform (DLT) method with normalization.
+ */
+function computeHomography(x0s, y0s, // source top-left
+x1s, y1s, // source top-right
+x2s, y2s, // source bottom-right
+x3s, y3s, // source bottom-left
+x0d, y0d, // dest top-left
+x1d, y1d, // dest top-right
+x2d, y2d, // dest bottom-right
+x3d, y3d // dest bottom-left
+) {
+    // Set up the 8x8 matrix equation Ah = 0
+    // Using the standard DLT formulation
+    const A = [
+        [x0s, y0s, 1, 0, 0, 0, -x0d * x0s, -x0d * y0s],
+        [0, 0, 0, x0s, y0s, 1, -y0d * x0s, -y0d * y0s],
+        [x1s, y1s, 1, 0, 0, 0, -x1d * x1s, -x1d * y1s],
+        [0, 0, 0, x1s, y1s, 1, -y1d * x1s, -y1d * y1s],
+        [x2s, y2s, 1, 0, 0, 0, -x2d * x2s, -x2d * y2s],
+        [0, 0, 0, x2s, y2s, 1, -y2d * x2s, -y2d * y2s],
+        [x3s, y3s, 1, 0, 0, 0, -x3d * x3s, -x3d * y3s],
+        [0, 0, 0, x3s, y3s, 1, -y3d * x3s, -y3d * y3s]
+    ];
+    const b = [x0d, y0d, x1d, y1d, x2d, y2d, x3d, y3d];
+    // Solve using Gaussian elimination
+    const h = solveLinearSystem(A, b);
+    if (!h)
+        return null;
+    // Return 3x3 matrix as flat array (row-major)
+    return [h[0], h[1], h[2], h[3], h[4], h[5], h[6], h[7], 1];
+}
+/**
+ * Solve a linear system Ax = b using Gaussian elimination with partial pivoting
+ */
+function solveLinearSystem(A, b) {
+    const n = A.length;
+    const augmented = A.map((row, i) => [...row, b[i]]);
+    // Forward elimination with partial pivoting
+    for (let col = 0; col < n; col++) {
+        // Find pivot
+        let maxRow = col;
+        for (let row = col + 1; row < n; row++) {
+            if (Math.abs(augmented[row][col]) > Math.abs(augmented[maxRow][col])) {
+                maxRow = row;
+            }
+        }
+        // Swap rows
+        [augmented[col], augmented[maxRow]] = [augmented[maxRow], augmented[col]];
+        // Check for singular matrix
+        if (Math.abs(augmented[col][col]) < 1e-10) {
+            return null;
+        }
+        // Eliminate column
+        for (let row = col + 1; row < n; row++) {
+            const factor = augmented[row][col] / augmented[col][col];
+            for (let j = col; j <= n; j++) {
+                augmented[row][j] -= factor * augmented[col][j];
+            }
+        }
+    }
+    // Back substitution
+    const x = new Array(n).fill(0);
+    for (let row = n - 1; row >= 0; row--) {
+        let sum = augmented[row][n];
+        for (let col = row + 1; col < n; col++) {
+            sum -= augmented[row][col] * x[col];
+        }
+        x[row] = sum / augmented[row][row];
+    }
+    return x;
+}
+/**
+ * Check if corners form a valid (non-degenerate) quadrilateral
+ */
+export function isValidQuad(corners) {
+    // Check that no two corners are at the same position
+    const points = [corners.tl, corners.tr, corners.br, corners.bl];
+    for (let i = 0; i < points.length; i++) {
+        for (let j = i + 1; j < points.length; j++) {
+            const dx = points[i].x - points[j].x;
+            const dy = points[i].y - points[j].y;
+            if (Math.sqrt(dx * dx + dy * dy) < 0.01) {
+                return false;
+            }
+        }
+    }
+    // Check that the quadrilateral is convex (no self-intersection)
+    // by checking the sign of cross products
+    const cross = (ax, ay, bx, by, cx, cy) => (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+    const signs = [
+        cross(corners.tl.x, corners.tl.y, corners.tr.x, corners.tr.y, corners.br.x, corners.br.y),
+        cross(corners.tr.x, corners.tr.y, corners.br.x, corners.br.y, corners.bl.x, corners.bl.y),
+        cross(corners.br.x, corners.br.y, corners.bl.x, corners.bl.y, corners.tl.x, corners.tl.y),
+        cross(corners.bl.x, corners.bl.y, corners.tl.x, corners.tl.y, corners.tr.x, corners.tr.y)
+    ];
+    // All signs should be the same for a convex quad
+    const allPositive = signs.every((s) => s > 0);
+    const allNegative = signs.every((s) => s < 0);
+    return allPositive || allNegative;
+}