@ume-group/contracts 0.2.1

package/dist/index.js

@@ -0,0 +1,1112 @@
+/**
+ * Shared types for Includu Platform
+ *
+ * Used by:
+ * - @includu/editor (timeline editor)
+ * - @includu/cms (video library)
+ */
+// ============================================================================
+// Debug Utilities
+// ============================================================================
+/**
+ * Debug flag - true in Vite dev mode, false in production builds.
+ * Can also be set manually for testing.
+ */
+export let DEBUG = !!import.meta.env?.DEV;
+/** Override the DEBUG flag (useful for testing or manual control) */
+export function setDebug(value) {
+    DEBUG = value;
+}
+/** Debug logger - only outputs when DEBUG is true (dev mode by default) */
+export function debug(...args) {
+    if (DEBUG)
+        console.log(...args);
+}
+/**
+ * Creates default corner offsets (no perspective adjustment)
+ */
+export function createDefaultCornerOffsets() {
+    return {
+        tl: { dx: 0, dy: 0 },
+        tr: { dx: 0, dy: 0 },
+        br: { dx: 0, dy: 0 },
+        bl: { dx: 0, dy: 0 }
+    };
+}
+/**
+ * Computes absolute corner positions from overlay position and corner offsets
+ * This is how corners are calculated for rendering
+ */
+export function computeCornersFromOffsets(position, offsets) {
+    // Base corners from overlay position (normalized 0-1)
+    const left = (position.x - position.width / 2) / 100;
+    const right = (position.x + position.width / 2) / 100;
+    const top = (position.y - position.height / 2) / 100;
+    const bottom = (position.y + position.height / 2) / 100;
+    // Apply offsets (convert from % of overlay size to normalized coordinates)
+    const widthNorm = position.width / 100;
+    const heightNorm = position.height / 100;
+    return {
+        tl: {
+            x: left + (offsets.tl.dx / 100) * widthNorm,
+            y: top + (offsets.tl.dy / 100) * heightNorm
+        },
+        tr: {
+            x: right + (offsets.tr.dx / 100) * widthNorm,
+            y: top + (offsets.tr.dy / 100) * heightNorm
+        },
+        br: {
+            x: right + (offsets.br.dx / 100) * widthNorm,
+            y: bottom + (offsets.br.dy / 100) * heightNorm
+        },
+        bl: {
+            x: left + (offsets.bl.dx / 100) * widthNorm,
+            y: bottom + (offsets.bl.dy / 100) * heightNorm
+        }
+    };
+}
+/**
+ * @deprecated Use createDefaultCornerOffsets instead
+ * Creates default corner points for a rectangular overlay
+ * Uses the overlay's position to calculate initial corner positions
+ */
+export function createDefaultCornerPoints(position) {
+    // Convert percentage position to normalized 0-1 coordinates
+    const left = (position.x - position.width / 2) / 100;
+    const right = (position.x + position.width / 2) / 100;
+    const top = (position.y - position.height / 2) / 100;
+    const bottom = (position.y + position.height / 2) / 100;
+    return {
+        tl: { x: left, y: top },
+        tr: { x: right, y: top },
+        br: { x: right, y: bottom },
+        bl: { x: left, y: bottom }
+    };
+}
+/**
+ * Migrate old absolute corners to new offset-based format
+ * Call this when loading projects with old corner format
+ */
+export function migrateToCornerOffsets(position, corners) {
+    // Calculate what the natural corners would be
+    const naturalLeft = (position.x - position.width / 2) / 100;
+    const naturalRight = (position.x + position.width / 2) / 100;
+    const naturalTop = (position.y - position.height / 2) / 100;
+    const naturalBottom = (position.y + position.height / 2) / 100;
+    const widthNorm = position.width / 100;
+    const heightNorm = position.height / 100;
+    // Calculate offsets as percentage of overlay dimensions
+    return {
+        tl: {
+            dx: widthNorm > 0 ? ((corners.tl.x - naturalLeft) / widthNorm) * 100 : 0,
+            dy: heightNorm > 0 ? ((corners.tl.y - naturalTop) / heightNorm) * 100 : 0
+        },
+        tr: {
+            dx: widthNorm > 0 ? ((corners.tr.x - naturalRight) / widthNorm) * 100 : 0,
+            dy: heightNorm > 0 ? ((corners.tr.y - naturalTop) / heightNorm) * 100 : 0
+        },
+        br: {
+            dx: widthNorm > 0 ? ((corners.br.x - naturalRight) / widthNorm) * 100 : 0,
+            dy: heightNorm > 0 ? ((corners.br.y - naturalBottom) / heightNorm) * 100 : 0
+        },
+        bl: {
+            dx: widthNorm > 0 ? ((corners.bl.x - naturalLeft) / widthNorm) * 100 : 0,
+            dy: heightNorm > 0 ? ((corners.bl.y - naturalBottom) / heightNorm) * 100 : 0
+        }
+    };
+}
+// ============================================================================
+// Recording Session Metadata
+// ============================================================================
+/**
+ * Session metadata for a recorded participation.
+ *
+ * Captures everything needed to re-publish the participant's recording
+ * as a new monetizable version with dynamic overlays and ads.
+ *
+ * Classify an overlay for recording: should it be burned into the video
+ * (static visual) or kept as dynamic metadata (interactive/monetizable)?
+ *
+ * Some overlays (e.g., clickable images) are BOTH — burned visually into
+ * the recording but also preserved as dynamic metadata so their click URL
+ * can be restored when re-publishing.
+ */
+export function classifyOverlayForRecording(overlay) {
+    switch (overlay.type) {
+        case 'cta':
+            return { burnable: false, dynamic: true };
+        case 'image': {
+            const content = overlay.content;
+            const hasClickUrl = !!(content.clickUrl?.trim());
+            // Images with click URLs are dynamic (ads/CTAs) — don't burn in
+            return { burnable: !hasClickUrl, dynamic: hasClickUrl };
+        }
+        // sprite-sequence and video: burnable in Phase 2 (not yet)
+        case 'sprite-sequence':
+        case 'video':
+            return { burnable: false, dynamic: false };
+        default:
+            // text, emoji, shape — always burn in
+            return { burnable: true, dynamic: false };
+    }
+}
+export const RECORDING_TIER_LIMITS = {
+    free: {
+        maxDurationMs: 3 * 60 * 1000, // 3 minutes
+        maxFileSize: 100 * 1024 * 1024, // 100 MB
+        label: 'Free (3 min)'
+    },
+    standard: {
+        maxDurationMs: 15 * 60 * 1000, // 15 minutes
+        maxFileSize: 300 * 1024 * 1024, // 300 MB
+        label: 'Standard (15 min)'
+    },
+    professional: {
+        maxDurationMs: 60 * 60 * 1000, // 60 minutes
+        maxFileSize: 500 * 1024 * 1024, // 500 MB
+        label: 'Professional (60 min)'
+    }
+};
+// ============================================================================
+// Standard Ad Slot Templates (Default Set)
+// ============================================================================
+/**
+ * Standard ad slot templates following IAB guidelines
+ * These are the default templates that Admetise provides.
+ * Can be extended/modified via Admetise admin.
+ */
+export const STANDARD_AD_TEMPLATES = [
+    // Video Ad Templates
+    {
+        id: 'preroll-15',
+        name: 'Standard Preroll (15s)',
+        description: 'Video ad before content starts, up to 15 seconds',
+        type: 'preroll',
+        category: 'video',
+        duration: 15,
+        maxDuration: 15,
+        active: true,
+        sortOrder: 1,
+        icon: 'play-circle'
+    },
+    {
+        id: 'preroll-30',
+        name: 'Extended Preroll (30s)',
+        description: 'Video ad before content starts, up to 30 seconds',
+        type: 'preroll',
+        category: 'video',
+        duration: 30,
+        maxDuration: 30,
+        active: true,
+        sortOrder: 2,
+        icon: 'play-circle'
+    },
+    {
+        id: 'midroll-15',
+        name: 'Standard Midroll (15s)',
+        description: 'Video ad during content, up to 15 seconds',
+        type: 'midroll',
+        category: 'video',
+        duration: 15,
+        maxDuration: 15,
+        active: true,
+        sortOrder: 10,
+        icon: 'pause-circle'
+    },
+    {
+        id: 'midroll-30',
+        name: 'Extended Midroll (30s)',
+        description: 'Video ad during content, up to 30 seconds',
+        type: 'midroll',
+        category: 'video',
+        duration: 30,
+        maxDuration: 30,
+        active: true,
+        sortOrder: 11,
+        icon: 'pause-circle'
+    },
+    {
+        id: 'postroll-15',
+        name: 'Standard Postroll (15s)',
+        description: 'Video ad after content ends, up to 15 seconds',
+        type: 'postroll',
+        category: 'video',
+        duration: 15,
+        maxDuration: 15,
+        active: true,
+        sortOrder: 20,
+        icon: 'stop-circle'
+    },
+    // Display Overlay Templates (IAB Standard Sizes)
+    {
+        id: 'overlay-leaderboard',
+        name: 'Leaderboard Overlay (728×90)',
+        description: 'Bottom banner overlay, IAB standard leaderboard',
+        type: 'overlay',
+        category: 'display',
+        width: 728,
+        height: 90,
+        position: 'bottom-left',
+        iabSize: '728x90',
+        active: true,
+        sortOrder: 30,
+        icon: 'rectangle-horizontal'
+    },
+    {
+        id: 'overlay-medium-rectangle',
+        name: 'Medium Rectangle Overlay (300×250)',
+        description: 'Corner overlay, IAB standard medium rectangle',
+        type: 'overlay',
+        category: 'display',
+        width: 300,
+        height: 250,
+        position: 'bottom-right',
+        iabSize: '300x250',
+        active: true,
+        sortOrder: 31,
+        icon: 'square'
+    },
+    {
+        id: 'overlay-banner',
+        name: 'Banner Overlay (468×60)',
+        description: 'Compact bottom banner overlay',
+        type: 'overlay',
+        category: 'display',
+        width: 468,
+        height: 60,
+        position: 'bottom-left',
+        iabSize: '468x60',
+        active: true,
+        sortOrder: 32,
+        icon: 'rectangle-horizontal'
+    },
+    // Companion Ad Templates
+    {
+        id: 'companion-medium-rectangle',
+        name: 'Companion Medium Rectangle (300×250)',
+        description: 'Companion ad displayed alongside video player',
+        type: 'companion',
+        category: 'companion',
+        width: 300,
+        height: 250,
+        iabSize: '300x250',
+        active: true,
+        sortOrder: 40,
+        icon: 'layout-sidebar-right'
+    },
+    {
+        id: 'companion-wide-skyscraper',
+        name: 'Companion Wide Skyscraper (160×600)',
+        description: 'Tall companion ad beside video player',
+        type: 'companion',
+        category: 'companion',
+        width: 160,
+        height: 600,
+        iabSize: '160x600',
+        active: true,
+        sortOrder: 41,
+        icon: 'layout-sidebar-right'
+    }
+];
+// ============================================================================
+// Utility Functions
+// ============================================================================
+/**
+ * Find a template by ID
+ *
+ * @param templateId - The template ID to find
+ * @param templates - Array of templates (defaults to STANDARD_AD_TEMPLATES)
+ * @returns The template or undefined
+ */
+export function findTemplate(templateId, templates = STANDARD_AD_TEMPLATES) {
+    return templates.find((t) => t.id === templateId);
+}
+/**
+ * Maps an AdSlotPlacement to an AdZone using template data
+ *
+ * @param placement - The placement from Includu
+ * @param template - The template definition from Admetise
+ * @param fps - Frames per second of the video
+ * @returns AdZone for Admetise
+ */
+export function mapPlacementToZone(placement, template, fps) {
+    return {
+        id: placement.id,
+        templateId: template.id,
+        type: template.type,
+        enabled: true,
+        presetPosition: template.position,
+        width: template.width,
+        height: template.height,
+        triggerTime: placement.triggerFrame ? placement.triggerFrame / fps : undefined,
+        triggerPercent: placement.triggerPercent,
+        maxDuration: template.maxDuration,
+        centerPosition: placement.position,
+        scale: placement.scale,
+        rotation: placement.rotation,
+        rotationX: placement.rotationX,
+        rotationY: placement.rotationY,
+        rotationEnabled: placement.rotationEnabled,
+        perspective: placement.perspective
+    };
+}
+/**
+ * @deprecated Use mapPlacementToZone instead
+ * Maps an Includu AdSlot to an Admetise AdZone (legacy support)
+ */
+export function mapAdSlotToZone(slot, fps) {
+    return {
+        id: slot.id,
+        templateId: slot.templateId || `legacy-${slot.type}`,
+        type: slot.type,
+        enabled: true,
+        presetPosition: slot.position,
+        width: slot.width,
+        height: slot.height,
+        triggerTime: slot.triggerFrame ? slot.triggerFrame / fps : undefined,
+        triggerPercent: slot.triggerPercent,
+        maxDuration: slot.maxDuration
+    };
+}
+/**
+ * Maps all placements from a manifest to AdZones
+ *
+ * @param manifest - Published manifest with monetization config
+ * @param templates - Available templates (defaults to STANDARD_AD_TEMPLATES)
+ * @returns Array of AdZones, or empty array if monetization disabled
+ */
+export function mapManifestToZones(manifest, templates = STANDARD_AD_TEMPLATES) {
+    if (!manifest.monetization?.enabled) {
+        return [];
+    }
+    // Prefer new placements field, fall back to legacy adSlots
+    if (manifest.monetization.placements?.length) {
+        return manifest.monetization.placements
+            .map((placement) => {
+            const template = findTemplate(placement.templateId, templates);
+            if (!template) {
+                console.warn(`Template not found: ${placement.templateId}`);
+                return null;
+            }
+            return mapPlacementToZone(placement, template, manifest.fps);
+        })
+            .filter((zone) => zone !== null);
+    }
+    // Legacy support for adSlots
+    if (manifest.monetization.adSlots?.length) {
+        return manifest.monetization.adSlots.map((slot) => mapAdSlotToZone(slot, manifest.fps));
+    }
+    return [];
+}
+/**
+ * Get templates grouped by category
+ *
+ * @param templates - Array of templates (defaults to STANDARD_AD_TEMPLATES)
+ * @returns Object with templates grouped by category
+ */
+export function getTemplatesByCategory(templates = STANDARD_AD_TEMPLATES) {
+    const result = {
+        video: [],
+        display: [],
+        companion: []
+    };
+    for (const template of templates.filter((t) => t.active)) {
+        result[template.category].push(template);
+    }
+    // Sort by sortOrder
+    for (const category of Object.keys(result)) {
+        result[category].sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0));
+    }
+    return result;
+}
+/**
+ * Get templates filtered by type
+ *
+ * @param type - The ad slot type to filter by
+ * @param templates - Array of templates (defaults to STANDARD_AD_TEMPLATES)
+ * @returns Filtered templates
+ */
+export function getTemplatesByType(type, templates = STANDARD_AD_TEMPLATES) {
+    return templates.filter((t) => t.active && t.type === type);
+}
+// ============================================================================
+// Perspective Transform Utilities
+// ============================================================================
+export { computeMatrix3d, isValidQuad } from './perspective';
+// ============================================================================
+// Layer 2: 3D Composite Types
+// ============================================================================
+export * from './layer2';
+// ============================================================================
+// Admetise Campaign Types (F1)
+// ============================================================================
+export * from './campaigns';
+// ============================================================================
+// Admetise Ad Serving Contracts (Player ↔ Admetise boundary)
+// ============================================================================
+export * from './adserving';
+// ============================================================================
+// Gausst Coordinate System Utilities
+// ============================================================================
+export * from './gausst';
+/**
+ * Standard overlay template presets
+ * Designed for ease of use across all devices
+ */
+export const OVERLAY_TEMPLATE_PRESETS = [
+    // ==================== LOWER THIRDS ====================
+    {
+        id: 'lower-third-name',
+        name: 'Name Card',
+        description: 'Speaker name and title',
+        category: 'lower-thirds',
+        icon: '👤',
+        type: 'text',
+        position: { x: 25, y: 85, width: 40, height: 12 },
+        durationSeconds: 5,
+        textDefaults: {
+            text: 'Speaker Name',
+            fontSize: 2.5,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'bold',
+            color: '#ffffff',
+            textAlign: 'left',
+            background: {
+                color: 'rgba(0, 0, 0, 0.7)',
+                opacity: 1,
+                padding: { x: 12, y: 8 },
+                scale: 1,
+                borderRadius: 4
+            }
+        }
+    },
+    {
+        id: 'lower-third-subtitle',
+        name: 'Subtitle Bar',
+        description: 'Full-width subtitle or caption',
+        category: 'lower-thirds',
+        icon: '💬',
+        type: 'text',
+        position: { x: 50, y: 90, width: 80, height: 8 },
+        durationSeconds: 4,
+        textDefaults: {
+            text: 'Your subtitle text here',
+            fontSize: 2,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'normal',
+            color: '#ffffff',
+            textAlign: 'center',
+            background: {
+                color: 'rgba(0, 0, 0, 0.6)',
+                opacity: 1,
+                padding: { x: 8, y: 6 },
+                scale: 1,
+                borderRadius: 4
+            }
+        }
+    },
+    // ==================== TITLES ====================
+    {
+        id: 'title-centered',
+        name: 'Center Title',
+        description: 'Large centered title',
+        category: 'titles',
+        icon: '🎬',
+        type: 'text',
+        position: { x: 50, y: 50, width: 70, height: 15 },
+        durationSeconds: 3,
+        textDefaults: {
+            text: 'Your Title',
+            fontSize: 4,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'bold',
+            color: '#ffffff',
+            textAlign: 'center',
+            background: {
+                color: 'rgba(0, 0, 0, 0.5)',
+                opacity: 1,
+                padding: { x: 15, y: 10 },
+                scale: 1,
+                borderRadius: 8
+            }
+        }
+    },
+    {
+        id: 'title-chapter',
+        name: 'Chapter Title',
+        description: 'Section or chapter heading',
+        category: 'titles',
+        icon: '📖',
+        type: 'text',
+        position: { x: 50, y: 15, width: 50, height: 10 },
+        durationSeconds: 3,
+        textDefaults: {
+            text: 'Chapter 1',
+            fontSize: 3,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'bold',
+            color: '#ffffff',
+            textAlign: 'center',
+            background: {
+                color: 'rgba(229, 57, 53, 0.9)',
+                opacity: 1,
+                padding: { x: 12, y: 6 },
+                scale: 1,
+                borderRadius: 4
+            }
+        }
+    },
+    // ==================== BADGES ====================
+    {
+        id: 'badge-corner',
+        name: 'Corner Badge',
+        description: 'Small badge in corner',
+        category: 'badges',
+        icon: '🏷️',
+        type: 'text',
+        position: { x: 90, y: 10, width: 15, height: 6 },
+        durationSeconds: 0, // 0 = show for entire video
+        textDefaults: {
+            text: 'LIVE',
+            fontSize: 1.5,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'bold',
+            color: '#ffffff',
+            textAlign: 'center',
+            background: {
+                color: 'rgba(229, 57, 53, 1)',
+                opacity: 1,
+                padding: { x: 10, y: 5 },
+                scale: 1,
+                borderRadius: 4
+            }
+        }
+    },
+    {
+        id: 'badge-new',
+        name: 'NEW Badge',
+        description: 'Highlight new content',
+        category: 'badges',
+        icon: '✨',
+        type: 'text',
+        position: { x: 10, y: 10, width: 12, height: 5 },
+        durationSeconds: 5,
+        textDefaults: {
+            text: 'NEW',
+            fontSize: 1.2,
+            fontFamily: 'Inter, sans-serif',
+            fontWeight: 'bold',
+            color: '#000000',
+            textAlign: 'center',
+            background: {
+                color: 'rgba(255, 235, 59, 1)',
+                opacity: 1,
+                padding: { x: 8, y: 4 },
+                scale: 1,
+                borderRadius: 12
+            }
+        }
+    },
+    // ==================== CTA ====================
+    {
+        id: 'cta-subscribe',
+        name: 'Subscribe Button',
+        description: 'Call to action button',
+        category: 'cta',
+        icon: '🔔',
+        type: 'cta',
+        position: { x: 85, y: 85, width: 20, height: 8 },
+        durationSeconds: 10,
+        ctaDefaults: {
+            text: 'Subscribe',
+            url: '#subscribe',
+            style: {
+                backgroundColor: '#E53935',
+                textColor: '#ffffff',
+                borderRadius: 8,
+                fontSize: 1.2, // em units
+                fontWeight: 'bold',
+                padding: { x: 20, y: 12 }
+            }
+        }
+    },
+    {
+        id: 'cta-learn-more',
+        name: 'Learn More',
+        description: 'Link to more info',
+        category: 'cta',
+        icon: '🔗',
+        type: 'cta',
+        position: { x: 50, y: 80, width: 25, height: 8 },
+        durationSeconds: 8,
+        ctaDefaults: {
+            text: 'Learn More',
+            url: '#',
+            style: {
+                backgroundColor: '#1976D2',
+                textColor: '#ffffff',
+                borderRadius: 24,
+                fontSize: 1.0, // em units
+                fontWeight: 'bold',
+                padding: { x: 24, y: 10 }
+            }
+        }
+    },
+    {
+        id: 'cta-picture-frame',
+        name: 'Clickable Picture Frame',
+        description: 'Clickable image overlay for promotions and links',
+        category: 'cta',
+        icon: '🖼️',
+        type: 'image',
+        position: { x: 50, y: 50, width: 30, height: 15 },
+        durationSeconds: 5,
+        imageDefaults: {
+            src: '',
+            alt: 'Clickable Picture Frame',
+            fit: 'contain',
+            opacity: 1,
+            borderRadius: 0,
+            clickUrl: '#'
+        }
+    },
+    // ==================== SOCIAL ====================
+    {
+        id: 'social-reaction',
+        name: 'Reaction',
+        description: 'Emoji reaction',
+        category: 'social',
+        icon: '😀',
+        type: 'emoji',
+        position: { x: 15, y: 50, width: 10, height: 10 },
+        durationSeconds: 2,
+        emojiDefaults: {
+            emoji: '👍',
+            size: 4
+        }
+    },
+    {
+        id: 'social-heart',
+        name: 'Heart',
+        description: 'Like/love reaction',
+        category: 'social',
+        icon: '❤️',
+        type: 'emoji',
+        position: { x: 85, y: 50, width: 10, height: 10 },
+        durationSeconds: 2,
+        emojiDefaults: {
+            emoji: '❤️',
+            size: 4
+        }
+    },
+    // ==================== GRAPHICS & LOGOS ====================
+    {
+        id: 'graphics-logo-corner',
+        name: 'Logo Bug',
+        description: 'Small logo in corner (watermark)',
+        category: 'graphics',
+        icon: '🏷️',
+        type: 'image',
+        position: { x: 90, y: 10, width: 12, height: 12 },
+        durationSeconds: 0, // 0 = full video duration
+        imageDefaults: {
+            src: '',
+            alt: 'Logo',
+            fit: 'contain',
+            opacity: 0.8,
+            borderRadius: 0
+        }
+    },
+    {
+        id: 'graphics-watermark-center',
+        name: 'Center Watermark',
+        description: 'Semi-transparent centered logo',
+        category: 'graphics',
+        icon: '💧',
+        type: 'image',
+        position: { x: 50, y: 50, width: 30, height: 30 },
+        durationSeconds: 0,
+        imageDefaults: {
+            src: '',
+            alt: 'Watermark',
+            fit: 'contain',
+            opacity: 0.3,
+            borderRadius: 0
+        }
+    },
+    {
+        id: 'graphics-banner',
+        name: 'Image Banner',
+        description: 'Full-width image banner',
+        category: 'graphics',
+        icon: '🖼️',
+        type: 'image',
+        position: { x: 50, y: 90, width: 80, height: 15 },
+        durationSeconds: 5,
+        imageDefaults: {
+            src: '',
+            alt: 'Banner',
+            fit: 'contain',
+            opacity: 1,
+            borderRadius: 8
+        }
+    },
+    {
+        id: 'graphics-sponsor',
+        name: 'Sponsor Logo',
+        description: 'Sponsor or partner logo placement',
+        category: 'graphics',
+        icon: '🤝',
+        type: 'image',
+        position: { x: 10, y: 10, width: 15, height: 10 },
+        durationSeconds: 10,
+        imageDefaults: {
+            src: '',
+            alt: 'Sponsor',
+            fit: 'contain',
+            opacity: 1,
+            borderRadius: 4
+        }
+    },
+    {
+        id: 'social-picture-frame',
+        name: 'Picture Frame',
+        description: 'Image overlay for photos and graphics',
+        category: 'social',
+        icon: '🖼️',
+        type: 'image',
+        position: { x: 50, y: 50, width: 30, height: 15 },
+        durationSeconds: 5,
+        imageDefaults: {
+            src: '',
+            alt: 'Picture Frame',
+            fit: 'contain',
+            opacity: 1,
+            borderRadius: 0
+        }
+    },
+    // ==================== MOTION GRAPHICS ====================
+    {
+        id: 'motiongfx-sprite',
+        name: 'Sprite Animation',
+        description: 'Animated sprite sequence (pre-rendered effects, mascots, particles)',
+        category: 'motion-gfx',
+        icon: '🎬',
+        type: 'sprite-sequence',
+        position: { x: 50, y: 50, width: 20, height: 20 },
+        durationSeconds: 5,
+        spriteDefaults: {
+            spritesheetUrl: '',
+            frameWidth: 256,
+            frameHeight: 256,
+            frameCount: 1,
+            columns: 1,
+            framesPerSecond: 12,
+            loop: true,
+            opacity: 1
+        }
+    },
+    {
+        id: 'motiongfx-video',
+        name: 'Video Overlay',
+        description: 'Video with alpha channel (WebM VP9, animated effects, transitions)',
+        category: 'motion-gfx',
+        icon: '🎥',
+        type: 'video',
+        position: { x: 50, y: 50, width: 30, height: 30 },
+        durationSeconds: 5,
+        videoDefaults: {
+            videoUrl: '',
+            loop: true,
+            muted: true,
+            opacity: 1,
+            fit: 'contain'
+        }
+    }
+];
+/**
+ * Get overlay templates by category
+ */
+export function getOverlayTemplatesByCategory(category) {
+    return OVERLAY_TEMPLATE_PRESETS.filter((t) => t.category === category);
+}
+/**
+ * Find an overlay template by ID
+ */
+export function findOverlayTemplate(id) {
+    return OVERLAY_TEMPLATE_PRESETS.find((t) => t.id === id);
+}
+/** Category labels for display */
+const CATEGORY_LABELS = {
+    'lower-thirds': 'Lower Thirds',
+    titles: 'Titles',
+    badges: 'Badges',
+    cta: 'Call to Action',
+    social: 'Social & Reactions',
+    graphics: 'Graphics & Logos',
+    'motion-gfx': 'Motion Graphics'
+};
+/**
+ * Get all overlay template categories with their templates
+ */
+export function getOverlayTemplateCategoriesWithTemplates() {
+    const categories = ['lower-thirds', 'titles', 'badges', 'cta', 'social', 'graphics'];
+    return categories.map((category) => ({
+        category,
+        label: CATEGORY_LABELS[category],
+        templates: getOverlayTemplatesByCategory(category)
+    }));
+}
+/**
+ * Get overlay template categories for the Overlays track (excludes branding categories)
+ */
+export function getOverlayTrackCategories() {
+    // Categories that go on the Overlays timeline track
+    const overlayCategories = ['lower-thirds', 'titles', 'badges', 'cta', 'social'];
+    return overlayCategories.map((category) => ({
+        category,
+        label: CATEGORY_LABELS[category],
+        templates: getOverlayTemplatesByCategory(category)
+    }));
+}
+/**
+ * Get branding template categories for the Branding track
+ */
+export function getBrandingTrackCategories() {
+    // Categories that go on the Branding timeline track
+    const brandingCategories = ['graphics'];
+    return brandingCategories.map((category) => ({
+        category,
+        label: CATEGORY_LABELS[category],
+        templates: getOverlayTemplatesByCategory(category)
+    }));
+}
+/**
+ * Get Motion Graphics template categories for the Motion GFX track
+ */
+export function getMotionGfxTrackCategories() {
+    // Categories that go on the Motion GFX timeline track
+    const motionGfxCategories = ['motion-gfx'];
+    return motionGfxCategories.map((category) => ({
+        category,
+        label: CATEGORY_LABELS[category],
+        templates: getOverlayTemplatesByCategory(category)
+    }));
+}
+/**
+ * @deprecated Use getMotionGfxTrackCategories instead
+ */
+export function get3DTrackCategories() {
+    return getMotionGfxTrackCategories();
+}
+// ============================================================================
+// Coordinate System (Three.js / Metric)
+// ============================================================================
+/**
+ * Coordinate system constants for Three.js video compositing
+ *
+ * Based on Gausst legacy code (Patent US8761580B2):
+ * - Y-up axis (Three.js default)
+ * - Metric units: 1 unit = 1 meter
+ * - Reference: 1920 video pixels = 1 meter
+ *
+ * @see docs/architecture/coordinate-system-design.md
+ */
+export const COORDINATE_SYSTEM = {
+    /**
+     * Reference scale: 1920 pixels = 1 meter in world space
+     * This ensures a standard 1920×1080 video is 1m × 0.5625m
+     */
+    PIXELS_PER_METER: 1920,
+    /**
+     * Layer Z positions in meters
+     * - VIDEO: Background video plane
+     * - THREE_D_MIN/MAX: 3D tracked surfaces, webcam
+     * - HUD_MIN/MAX: HTML overlays via CSS2DRenderer
+     */
+    LAYER_Z: {
+        VIDEO: 0,
+        THREE_D_MIN: 0.01,
+        THREE_D_MAX: 10,
+        HUD_MIN: 10.1,
+        HUD_MAX: 100
+    },
+    /**
+     * Camera defaults for orthographic rendering (video plane)
+     */
+    CAMERA: {
+        NEAR: 0.01,
+        FAR: 1000,
+        POSITION_Z: 50 // Camera 50m from video plane
+    },
+    /**
+     * Orthographic camera settings for HUD overlays (Layer 3)
+     * Provides predictable 2D positioning for sprites, text, CTAs
+     *
+     * Bounds are set dynamically based on video dimensions.
+     * Objects are positioned in meters relative to center (0,0).
+     */
+    HUD_CAMERA: {
+        /** Camera Z position (arbitrary for orthographic) */
+        POSITION_Z: 10,
+        /** Near clipping plane */
+        NEAR: 0.1,
+        /** Far clipping plane */
+        FAR: 100,
+        /** Default object Z position */
+        OBJECT_Z: 0
+    },
+    /**
+     * Perspective camera settings for webcam composite layer (Layer 2)
+     * Camera positioned at eye height for 3D scene placement
+     * Reserved for future webcam/chroma key compositing
+     */
+    SCENE_CAMERA: {
+        /** Camera X position (centered) */
+        POSITION_X: 0,
+        /** Camera Y position (eye height) */
+        POSITION_Y: 1.2,
+        /** Camera Z position (distance from scene) */
+        POSITION_Z: 4,
+        /** Vertical field of view in degrees (~43mm equivalent) */
+        FOV: 47,
+        /** Near clipping plane */
+        NEAR: 0.1,
+        /** Far clipping plane */
+        FAR: 100,
+        /** Look-at target Y position */
+        LOOK_AT_Y: 1.2
+    },
+    /**
+     * Film gate constants (for future camera matching)
+     * Based on 35mm full-frame sensor
+     */
+    FILM_GATE: {
+        HORIZONTAL_APERTURE: 1.417, // inches (36mm)
+        VERTICAL_APERTURE: 0.945 // inches (24mm)
+    }
+};
+/**
+ * Convert video pixel dimensions to world-space meters
+ *
+ * @param pixelWidth - Video width in pixels
+ * @param pixelHeight - Video height in pixels
+ * @returns World-space dimensions in meters
+ */
+export function pixelsToMeters(pixelWidth, pixelHeight) {
+    return {
+        width: pixelWidth / COORDINATE_SYSTEM.PIXELS_PER_METER,
+        height: pixelHeight / COORDINATE_SYSTEM.PIXELS_PER_METER
+    };
+}
+/**
+ * Convert world-space meters to video pixels
+ *
+ * @param meterWidth - Width in meters
+ * @param meterHeight - Height in meters
+ * @returns Pixel dimensions
+ */
+export function metersToPixels(meterWidth, meterHeight) {
+    return {
+        width: meterWidth * COORDINATE_SYSTEM.PIXELS_PER_METER,
+        height: meterHeight * COORDINATE_SYSTEM.PIXELS_PER_METER
+    };
+}
+/**
+ * Convert overlay percentage position (0-100) to world-space meters
+ *
+ * @param percentX - X position as percentage (0-100, left to right)
+ * @param percentY - Y position as percentage (0-100, top to bottom)
+ * @param videoWidthMeters - Video width in meters
+ * @param videoHeightMeters - Video height in meters
+ * @returns World-space position {x, y} in meters, centered at origin
+ */
+export function percentToWorldSpace(percentX, percentY, videoWidthMeters, videoHeightMeters) {
+    // Convert percentage (0-100) to normalized (-0.5 to 0.5)
+    const normalizedX = (percentX - 50) / 100;
+    const normalizedY = (50 - percentY) / 100; // Y inverted for screen coords
+    return {
+        x: normalizedX * videoWidthMeters,
+        y: normalizedY * videoHeightMeters
+    };
+}
+/**
+ * Convert world-space meters to overlay percentage position (0-100)
+ *
+ * @param worldX - X position in meters (origin = center)
+ * @param worldY - Y position in meters (origin = center)
+ * @param videoWidthMeters - Video width in meters
+ * @param videoHeightMeters - Video height in meters
+ * @returns Percentage position {x, y} (0-100)
+ */
+export function worldSpaceToPercent(worldX, worldY, videoWidthMeters, videoHeightMeters) {
+    const normalizedX = worldX / videoWidthMeters;
+    const normalizedY = worldY / videoHeightMeters;
+    return {
+        x: normalizedX * 100 + 50,
+        y: 50 - normalizedY * 100 // Y inverted for screen coords
+    };
+}
+/**
+ * Convert Gausst tracking packet to world-space transform
+ *
+ * @param packet - Raw tracking data from hardware
+ * @returns Position in meters, rotation in radians, FOV in degrees
+ */
+export function trackingPacketToWorldSpace(packet) {
+    const DEG_TO_RAD = Math.PI / 180;
+    return {
+        position: {
+            x: packet.x / 100000, // mm×100 → meters
+            y: packet.y / 100000,
+            z: packet.z / 100000
+        },
+        rotation: {
+            x: (packet.tilt / 1000) * DEG_TO_RAD, // Tilt (pitch)
+            y: (-packet.pan / 1000) * DEG_TO_RAD, // Pan (yaw), negated per Gausst
+            z: (packet.roll / 1000) * DEG_TO_RAD // Roll
+        },
+        fov: packet.fov / 1000
+    };
+}
+/**
+ * Convert FOV to focal length (for matching real camera optics)
+ *
+ * Formula from Gausst: focalLength = (aperture / 2) / tan(fov / 2) * 25.4
+ *
+ * @param fovDegrees - Field of view in degrees
+ * @param filmApertureInches - Horizontal film aperture (default: 1.417" = 36mm)
+ * @returns Focal length in millimeters
+ */
+export function fovToFocalLength(fovDegrees, filmApertureInches = COORDINATE_SYSTEM.FILM_GATE.HORIZONTAL_APERTURE) {
+    const fovRadians = fovDegrees * (Math.PI / 180);
+    const apertureMM = filmApertureInches * 25.4;
+    return (apertureMM / 2) / Math.tan(fovRadians / 2);
+}
+/**
+ * Convert focal length to FOV
+ *
+ * @param focalLengthMM - Focal length in millimeters
+ * @param filmApertureInches - Horizontal film aperture (default: 1.417" = 36mm)
+ * @returns Field of view in degrees
+ */
+export function focalLengthToFov(focalLengthMM, filmApertureInches = COORDINATE_SYSTEM.FILM_GATE.HORIZONTAL_APERTURE) {
+    const apertureMM = filmApertureInches * 25.4;
+    const fovRadians = 2 * Math.atan((apertureMM / 2) / focalLengthMM);
+    return fovRadians * (180 / Math.PI);
+}
+// ============================================================================
+// Layer 2 (WebGL/3D) Module Re-exports
+// ============================================================================
+// Shader exports
+export { webcamVertexShader, webcamFragmentShader, getDefaultPlayerUniforms, getDefaultEditorUniforms } from './layer2/shaders';
+// Webcam utility exports
+export { WEBCAM_BASE_HEIGHT_METERS, SILHOUETTE_HEIGHT_RATIO, getWebcamBaseDimensions, getWebcamMeshYOffset, getObjectEuler, getCameraEuler, GAM_PIXELS_TO_METERS, AD_TEMPLATE_DIMENSIONS, getAdDimensions, CHROMA_KEY_COLORS, getChromaKeyColorHex, featherToUV, featherEdgesToUV } from './layer2/webcam-utils';
+// ============================================================================
+// Segmentation Module
+// ============================================================================
+// NOTE: MediaPipeSegmenter is NOT exported from main entry point because
+// @mediapipe/tasks-vision requires browser APIs and breaks SSR.
+// Import directly from '@ume/contracts/segmentation' in browser contexts:
+//   import { MediaPipeSegmenter } from '@ume/contracts/segmentation';
+// ============================================================================