ugcinc-render 1.3.14 → 1.5.0

package/dist/index.d.mts

@@ -337,27 +337,47 @@ interface ImageEditorNodeConfig {
 }
 
 /**
- * Video editor types for rendering
+ * Video editor types for the WEBAPP UI
+ *
+ * These types include UI-only fields (marked with comments).
+ * The renderer uses types from editor.ts and segment.ts instead.
+ *
+ * UI-only fields are stripped before sending to renderer:
+ * - timeMode: UI helper for displaying timing mode
+ * - inputRef/textInputRef: Resolved to source/text before rendering
+ * - dimensionPreset: Renderer uses width/height directly
+ * - previewUrls/previewTextValues: Only for UI preview
  */
 
 /**
- * UI helper for timing mode
+ * UI helper for timing mode - not sent to renderer
  */
 type TimeMode = 'fixed' | 'flexible';
 /**
- * Base properties for all video editor segments
+ * Base properties for all video editor segments (UI)
  */
 interface VideoEditorBaseSegment {
+    /** Unique segment identifier */
     id: string;
+    /** Order in the channel (0-based) */
     order: number;
+    /** Time offset from previous segment or absolute position */
     offset: TimeValue;
+    /** Segment duration - required for sequential playback */
     duration?: TimeValue;
+    /** Trim from start in milliseconds */
     startTrim?: number;
+    /** Trim from end in milliseconds */
     endTrim?: number;
+    /** UI-only: helper for timing mode display - stripped before rendering */
     timeMode?: TimeMode;
+    /** Parent segment ID for overlays */
     parentId?: string;
+    /** Relative start (0-1) within parent for overlays */
     relativeStart?: number;
+    /** Relative end (0-1) within parent for overlays */
     relativeEnd?: number;
+    /** Fade-in duration in milliseconds */
     fadeIn?: number;
 }
 /**
@@ -374,11 +394,13 @@ interface VideoEditorVisualSegment extends VideoEditorBaseSegment {
     opacity?: number;
 }
 /**
- * Video segment
+ * Video segment (UI)
  */
 interface VideoEditorVideoSegment extends VideoEditorVisualSegment {
     type: 'video';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     fit?: FitMode;
     speed?: number;
@@ -386,31 +408,37 @@ interface VideoEditorVideoSegment extends VideoEditorVisualSegment {
     borderRadius?: number | BorderRadiusConfig;
 }
 /**
- * Audio segment
+ * Audio segment (UI)
  */
 interface VideoEditorAudioSegment extends VideoEditorBaseSegment {
     type: 'audio';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     volume?: number;
 }
 /**
- * Image segment
+ * Image segment (UI)
  */
 interface VideoEditorImageSegment extends VideoEditorVisualSegment {
     type: 'image';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     fit?: FitMode;
     loop?: boolean;
     borderRadius?: number | BorderRadiusConfig;
 }
 /**
- * Text segment
+ * Text segment (UI)
  */
 interface VideoEditorTextSegment extends VideoEditorVisualSegment {
     type: 'text';
+    /** UI-only: reference to text input - resolved to text before rendering */
     textInputRef?: string;
+    /** Actual text content (set after textInputRef is resolved) */
     text?: string;
     alignment?: 'left' | 'center' | 'right' | 'justify';
     verticalAlign?: 'top' | 'middle' | 'bottom';
@@ -445,18 +473,36 @@ interface VideoEditorChannel {
     segments: VideoEditorSegment[];
 }
 /**
- * Video editor node configuration
+ * Video editor node configuration for WEBAPP UI
+ *
+ * Duration is NOT stored - it's calculated from segment durations.
+ * dimensionPreset, previewUrls, previewTextValues are UI-only.
  */
 interface VideoEditorNodeConfig {
+    /** Canvas width in pixels */
     width: number;
+    /** Canvas height in pixels */
     height: number;
+    /** Frames per second */
     fps: number;
-    duration?: number;
+    /** UI-only: dimension preset selector */
     dimensionPreset: DimensionPresetKey;
+    /** Channels containing segments */
     channels: VideoEditorChannel[];
+    /** UI-only: preview URLs for displaying in editor */
     previewUrls?: Record<string, string>;
+    /** UI-only: preview text values for displaying in editor */
     previewTextValues?: Record<string, string>;
 }
+/**
+ * Segment position on timeline (calculated from segment timing properties)
+ */
+interface SegmentTimelinePosition {
+    /** Start time in milliseconds */
+    startMs: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
 
 /**
  * Segment types for the rendering system
@@ -635,15 +681,16 @@ type VisualSegmentUnion = VideoSegment | ImageSegment | TextSegment;
 type StaticSegment = ImageSegment | TextSegment;
 
 /**
- * Editor configuration types
+ * Editor configuration types for RENDERING
+ *
+ * These types define what the renderer receives.
+ * Duration is always calculated from segments - there is no duration field.
  *
- * Editors are the top-level containers that define the canvas dimensions,
- * timing, and channels containing segments.
+ * Note: UI-specific types (with previewUrls, dimensionPreset, etc.) are in video.ts
  */
 
 /**
- * A channel (track) containing segments
- * Channels allow for parallel playback of segments
+ * A channel (track) containing segments for rendering
  */
 interface Channel<T extends Segment = Segment> {
     /** Unique channel identifier */
@@ -652,17 +699,16 @@ interface Channel<T extends Segment = Segment> {
     segments: T[];
 }
 /**
- * Base editor configuration shared by all editor types
+ * Base editor configuration for rendering
+ * Duration is calculated from segments, not stored.
  */
 interface BaseEditorConfig {
     /** Canvas width in pixels */
     width: number;
     /** Canvas height in pixels */
     height: number;
-    /** Frames per second (video only) */
+    /** Frames per second */
     fps: number;
-    /** Total duration in milliseconds (auto-calculated if 0 or undefined) */
-    duration?: number;
 }
 /**
  * Full editor configuration with all segment types
@@ -1165,6 +1211,68 @@ declare function calculateCropBounds(elements: ImageEditorElement[], dynamicCrop
  */
 declare function isDynamicCropEnabled(dynamicCrop: DynamicCropConfig | undefined): boolean;
 
+/**
+ * Timeline utility functions for video editor
+ *
+ * These functions calculate segment positions on the timeline based on
+ * the segment/overlay timing model. Used by both the webapp UI and
+ * the VideoEditorComposition for rendering.
+ */
+
+/**
+ * Create a default TimeValue for segment offsets
+ */
+declare function defaultOffset(mode?: TimeMode): TimeValue;
+/**
+ * Get base segments (no parentId) for a channel
+ * Base segments are the primary timeline elements that overlays attach to
+ */
+declare function getBaseSegments(channel: VideoEditorChannel): VideoEditorSegment[];
+/**
+ * Get overlays for a specific parent segment (or global overlays if parentId is null)
+ */
+declare function getOverlays(channel: VideoEditorChannel, parentId: string | null): VideoEditorSegment[];
+/**
+ * Calculate segment position on timeline
+ *
+ * For base segments:
+ * - Position is calculated from offset and previous segments
+ * - Duration is from the duration property or default (5 seconds)
+ *
+ * For overlay segments:
+ * - Position is calculated relative to parent using relativeStart/relativeEnd
+ * - relativeStart/relativeEnd are fractions (0-1) of parent duration
+ */
+declare function getSegmentTimelinePosition(segment: VideoEditorSegment, baseSegments: VideoEditorSegment[], channel: VideoEditorChannel): SegmentTimelinePosition;
+/**
+ * Check if a segment is visible at a given time
+ */
+declare function isSegmentVisibleAtTime(segment: VideoEditorSegment, time: number, channel: VideoEditorChannel): boolean;
+/**
+ * Calculate estimated total duration based on segments
+ */
+declare function calculateEstimatedDuration(channels: VideoEditorChannel[]): number;
+/**
+ * Calculate the timeline content end time (used for both ruler and scroll width)
+ */
+declare function calculateTimelineContentEnd(channel: VideoEditorChannel): number;
+/**
+ * Format time in mm:ss.ms
+ */
+declare function formatTime(ms: number): string;
+/**
+ * Parse time string to milliseconds
+ */
+declare function parseTime(timeStr: string): number;
+/**
+ * Generate a unique segment ID
+ */
+declare function generateSegmentId(): string;
+/**
+ * Generate a unique overlay ID
+ */
+declare function generateOverlayId(): string;
+
 /**
  * Hook exports for ugcinc-render
  *
@@ -1224,4 +1332,4 @@ declare function useResolvedPositions(elements: ImageEditorElement[], textValues
 
 declare const RenderRoot: React.FC;
 
-export { type AudioSegment, type BaseEditorConfig, type BaseSegment, type BorderRadiusConfig, type Channel, type CropAxisConfig, type CropBoundary, type CropBounds, DIMENSION_PRESETS, type DimensionPreset, type DimensionPresetKey, type DynamicCropConfig, type EditorConfig, type EditorSegment, FONT_FAMILIES, FONT_URLS, type FitDimensions, type FitMode, type FontType, type FontWeight, type HorizontalAnchor, type HorizontalSelfAnchor, type Hyphenation, IMAGE_DEFAULTS, ImageEditorComposition, type ImageEditorCompositionProps, type ImageEditorConfig, type ImageEditorElement, type ImageEditorNodeConfig, ImageElement, type ImageElementProps, type ImageSegment, type PictureSegment, type PositionResolutionError, type PositionResolutionResult, type RelativePositionConfigX, type RelativePositionConfigY, RenderRoot, type Segment, type SegmentType, type StaticSegment, TEXT_DEFAULTS, type TextAlignment, type TextDirection, TextElement, type TextElementProps, type TextOverflow, type TextSegment, type TextWrap, type TimeMode, type TimeValue, VIDEO_DEFAULTS, VISUAL_DEFAULTS, type VerticalAlignment, type VerticalAnchor, type VerticalSelfAnchor, type VideoEditorAudioSegment, type VideoEditorBaseSegment, type VideoEditorChannel, VideoEditorComposition, type VideoEditorCompositionProps, type VideoEditorConfig, type VideoEditorImageSegment, type VideoEditorNodeConfig, type VideoEditorSegment, type VideoEditorTextSegment, type VideoEditorVideoSegment, type VideoEditorVisualSegment, VideoElement, type VideoElementProps, type VideoSegment, type VisualSegment, type VisualSegmentUnion, type WordBreak, applyImageDefaults, applyTextDefaults, applyVideoDefaults, areFontsLoaded, buildFontString, calculateAutoWidthDimensions, calculateCropBounds, calculateFitDimensions, calculateLineWidth, canSetAsReference, getBorderRadii, getDependentElements, getFontFamily, getReferenceElementX, getReferenceElementY, hexToRgba, isDynamicCropEnabled, parseHexColor, preloadFonts, resolveElementPositions, useFontsLoaded, useImageLoader, useImagePreloader, useResolvedPositions, wrapText };
+export { type AudioSegment, type BaseEditorConfig, type BaseSegment, type BorderRadiusConfig, type Channel, type CropAxisConfig, type CropBoundary, type CropBounds, DIMENSION_PRESETS, type DimensionPreset, type DimensionPresetKey, type DynamicCropConfig, type EditorConfig, type EditorSegment, FONT_FAMILIES, FONT_URLS, type FitDimensions, type FitMode, type FontType, type FontWeight, type HorizontalAnchor, type HorizontalSelfAnchor, type Hyphenation, IMAGE_DEFAULTS, ImageEditorComposition, type ImageEditorCompositionProps, type ImageEditorConfig, type ImageEditorElement, type ImageEditorNodeConfig, ImageElement, type ImageElementProps, type ImageSegment, type PictureSegment, type PositionResolutionError, type PositionResolutionResult, type RelativePositionConfigX, type RelativePositionConfigY, RenderRoot, type Segment, type SegmentTimelinePosition, type SegmentType, type StaticSegment, TEXT_DEFAULTS, type TextAlignment, type TextDirection, TextElement, type TextElementProps, type TextOverflow, type TextSegment, type TextWrap, type TimeMode, type TimeValue, VIDEO_DEFAULTS, VISUAL_DEFAULTS, type VerticalAlignment, type VerticalAnchor, type VerticalSelfAnchor, type VideoEditorAudioSegment, type VideoEditorBaseSegment, type VideoEditorChannel, VideoEditorComposition, type VideoEditorCompositionProps, type VideoEditorConfig, type VideoEditorImageSegment, type VideoEditorNodeConfig, type VideoEditorSegment, type VideoEditorTextSegment, type VideoEditorVideoSegment, type VideoEditorVisualSegment, VideoElement, type VideoElementProps, type VideoSegment, type VisualSegment, type VisualSegmentUnion, type WordBreak, applyImageDefaults, applyTextDefaults, applyVideoDefaults, areFontsLoaded, buildFontString, calculateAutoWidthDimensions, calculateCropBounds, calculateEstimatedDuration, calculateFitDimensions, calculateLineWidth, calculateTimelineContentEnd, canSetAsReference, defaultOffset, formatTime, generateOverlayId, generateSegmentId, getBaseSegments, getBorderRadii, getDependentElements, getFontFamily, getOverlays, getReferenceElementX, getReferenceElementY, getSegmentTimelinePosition, hexToRgba, isDynamicCropEnabled, isSegmentVisibleAtTime, parseHexColor, parseTime, preloadFonts, resolveElementPositions, useFontsLoaded, useImageLoader, useImagePreloader, useResolvedPositions, wrapText };

package/dist/index.d.ts

@@ -337,27 +337,47 @@ interface ImageEditorNodeConfig {
 }
 
 /**
- * Video editor types for rendering
+ * Video editor types for the WEBAPP UI
+ *
+ * These types include UI-only fields (marked with comments).
+ * The renderer uses types from editor.ts and segment.ts instead.
+ *
+ * UI-only fields are stripped before sending to renderer:
+ * - timeMode: UI helper for displaying timing mode
+ * - inputRef/textInputRef: Resolved to source/text before rendering
+ * - dimensionPreset: Renderer uses width/height directly
+ * - previewUrls/previewTextValues: Only for UI preview
  */
 
 /**
- * UI helper for timing mode
+ * UI helper for timing mode - not sent to renderer
  */
 type TimeMode = 'fixed' | 'flexible';
 /**
- * Base properties for all video editor segments
+ * Base properties for all video editor segments (UI)
  */
 interface VideoEditorBaseSegment {
+    /** Unique segment identifier */
     id: string;
+    /** Order in the channel (0-based) */
     order: number;
+    /** Time offset from previous segment or absolute position */
     offset: TimeValue;
+    /** Segment duration - required for sequential playback */
     duration?: TimeValue;
+    /** Trim from start in milliseconds */
     startTrim?: number;
+    /** Trim from end in milliseconds */
     endTrim?: number;
+    /** UI-only: helper for timing mode display - stripped before rendering */
     timeMode?: TimeMode;
+    /** Parent segment ID for overlays */
     parentId?: string;
+    /** Relative start (0-1) within parent for overlays */
     relativeStart?: number;
+    /** Relative end (0-1) within parent for overlays */
     relativeEnd?: number;
+    /** Fade-in duration in milliseconds */
     fadeIn?: number;
 }
 /**
@@ -374,11 +394,13 @@ interface VideoEditorVisualSegment extends VideoEditorBaseSegment {
     opacity?: number;
 }
 /**
- * Video segment
+ * Video segment (UI)
  */
 interface VideoEditorVideoSegment extends VideoEditorVisualSegment {
     type: 'video';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     fit?: FitMode;
     speed?: number;
@@ -386,31 +408,37 @@ interface VideoEditorVideoSegment extends VideoEditorVisualSegment {
     borderRadius?: number | BorderRadiusConfig;
 }
 /**
- * Audio segment
+ * Audio segment (UI)
  */
 interface VideoEditorAudioSegment extends VideoEditorBaseSegment {
     type: 'audio';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     volume?: number;
 }
 /**
- * Image segment
+ * Image segment (UI)
  */
 interface VideoEditorImageSegment extends VideoEditorVisualSegment {
     type: 'image';
+    /** UI-only: reference to input node - resolved to source before rendering */
     inputRef?: string;
+    /** Actual source URL (set after inputRef is resolved) */
     source?: string;
     fit?: FitMode;
     loop?: boolean;
     borderRadius?: number | BorderRadiusConfig;
 }
 /**
- * Text segment
+ * Text segment (UI)
  */
 interface VideoEditorTextSegment extends VideoEditorVisualSegment {
     type: 'text';
+    /** UI-only: reference to text input - resolved to text before rendering */
     textInputRef?: string;
+    /** Actual text content (set after textInputRef is resolved) */
     text?: string;
     alignment?: 'left' | 'center' | 'right' | 'justify';
     verticalAlign?: 'top' | 'middle' | 'bottom';
@@ -445,18 +473,36 @@ interface VideoEditorChannel {
     segments: VideoEditorSegment[];
 }
 /**
- * Video editor node configuration
+ * Video editor node configuration for WEBAPP UI
+ *
+ * Duration is NOT stored - it's calculated from segment durations.
+ * dimensionPreset, previewUrls, previewTextValues are UI-only.
  */
 interface VideoEditorNodeConfig {
+    /** Canvas width in pixels */
     width: number;
+    /** Canvas height in pixels */
     height: number;
+    /** Frames per second */
     fps: number;
-    duration?: number;
+    /** UI-only: dimension preset selector */
     dimensionPreset: DimensionPresetKey;
+    /** Channels containing segments */
     channels: VideoEditorChannel[];
+    /** UI-only: preview URLs for displaying in editor */
     previewUrls?: Record<string, string>;
+    /** UI-only: preview text values for displaying in editor */
     previewTextValues?: Record<string, string>;
 }
+/**
+ * Segment position on timeline (calculated from segment timing properties)
+ */
+interface SegmentTimelinePosition {
+    /** Start time in milliseconds */
+    startMs: number;
+    /** Duration in milliseconds */
+    durationMs: number;
+}
 
 /**
  * Segment types for the rendering system
@@ -635,15 +681,16 @@ type VisualSegmentUnion = VideoSegment | ImageSegment | TextSegment;
 type StaticSegment = ImageSegment | TextSegment;
 
 /**
- * Editor configuration types
+ * Editor configuration types for RENDERING
+ *
+ * These types define what the renderer receives.
+ * Duration is always calculated from segments - there is no duration field.
  *
- * Editors are the top-level containers that define the canvas dimensions,
- * timing, and channels containing segments.
+ * Note: UI-specific types (with previewUrls, dimensionPreset, etc.) are in video.ts
  */
 
 /**
- * A channel (track) containing segments
- * Channels allow for parallel playback of segments
+ * A channel (track) containing segments for rendering
  */
 interface Channel<T extends Segment = Segment> {
     /** Unique channel identifier */
@@ -652,17 +699,16 @@ interface Channel<T extends Segment = Segment> {
     segments: T[];
 }
 /**
- * Base editor configuration shared by all editor types
+ * Base editor configuration for rendering
+ * Duration is calculated from segments, not stored.
  */
 interface BaseEditorConfig {
     /** Canvas width in pixels */
     width: number;
     /** Canvas height in pixels */
     height: number;
-    /** Frames per second (video only) */
+    /** Frames per second */
     fps: number;
-    /** Total duration in milliseconds (auto-calculated if 0 or undefined) */
-    duration?: number;
 }
 /**
  * Full editor configuration with all segment types
@@ -1165,6 +1211,68 @@ declare function calculateCropBounds(elements: ImageEditorElement[], dynamicCrop
  */
 declare function isDynamicCropEnabled(dynamicCrop: DynamicCropConfig | undefined): boolean;
 
+/**
+ * Timeline utility functions for video editor
+ *
+ * These functions calculate segment positions on the timeline based on
+ * the segment/overlay timing model. Used by both the webapp UI and
+ * the VideoEditorComposition for rendering.
+ */
+
+/**
+ * Create a default TimeValue for segment offsets
+ */
+declare function defaultOffset(mode?: TimeMode): TimeValue;
+/**
+ * Get base segments (no parentId) for a channel
+ * Base segments are the primary timeline elements that overlays attach to
+ */
+declare function getBaseSegments(channel: VideoEditorChannel): VideoEditorSegment[];
+/**
+ * Get overlays for a specific parent segment (or global overlays if parentId is null)
+ */
+declare function getOverlays(channel: VideoEditorChannel, parentId: string | null): VideoEditorSegment[];
+/**
+ * Calculate segment position on timeline
+ *
+ * For base segments:
+ * - Position is calculated from offset and previous segments
+ * - Duration is from the duration property or default (5 seconds)
+ *
+ * For overlay segments:
+ * - Position is calculated relative to parent using relativeStart/relativeEnd
+ * - relativeStart/relativeEnd are fractions (0-1) of parent duration
+ */
+declare function getSegmentTimelinePosition(segment: VideoEditorSegment, baseSegments: VideoEditorSegment[], channel: VideoEditorChannel): SegmentTimelinePosition;
+/**
+ * Check if a segment is visible at a given time
+ */
+declare function isSegmentVisibleAtTime(segment: VideoEditorSegment, time: number, channel: VideoEditorChannel): boolean;
+/**
+ * Calculate estimated total duration based on segments
+ */
+declare function calculateEstimatedDuration(channels: VideoEditorChannel[]): number;
+/**
+ * Calculate the timeline content end time (used for both ruler and scroll width)
+ */
+declare function calculateTimelineContentEnd(channel: VideoEditorChannel): number;
+/**
+ * Format time in mm:ss.ms
+ */
+declare function formatTime(ms: number): string;
+/**
+ * Parse time string to milliseconds
+ */
+declare function parseTime(timeStr: string): number;
+/**
+ * Generate a unique segment ID
+ */
+declare function generateSegmentId(): string;
+/**
+ * Generate a unique overlay ID
+ */
+declare function generateOverlayId(): string;
+
 /**
  * Hook exports for ugcinc-render
  *
@@ -1224,4 +1332,4 @@ declare function useResolvedPositions(elements: ImageEditorElement[], textValues
 
 declare const RenderRoot: React.FC;
 
-export { type AudioSegment, type BaseEditorConfig, type BaseSegment, type BorderRadiusConfig, type Channel, type CropAxisConfig, type CropBoundary, type CropBounds, DIMENSION_PRESETS, type DimensionPreset, type DimensionPresetKey, type DynamicCropConfig, type EditorConfig, type EditorSegment, FONT_FAMILIES, FONT_URLS, type FitDimensions, type FitMode, type FontType, type FontWeight, type HorizontalAnchor, type HorizontalSelfAnchor, type Hyphenation, IMAGE_DEFAULTS, ImageEditorComposition, type ImageEditorCompositionProps, type ImageEditorConfig, type ImageEditorElement, type ImageEditorNodeConfig, ImageElement, type ImageElementProps, type ImageSegment, type PictureSegment, type PositionResolutionError, type PositionResolutionResult, type RelativePositionConfigX, type RelativePositionConfigY, RenderRoot, type Segment, type SegmentType, type StaticSegment, TEXT_DEFAULTS, type TextAlignment, type TextDirection, TextElement, type TextElementProps, type TextOverflow, type TextSegment, type TextWrap, type TimeMode, type TimeValue, VIDEO_DEFAULTS, VISUAL_DEFAULTS, type VerticalAlignment, type VerticalAnchor, type VerticalSelfAnchor, type VideoEditorAudioSegment, type VideoEditorBaseSegment, type VideoEditorChannel, VideoEditorComposition, type VideoEditorCompositionProps, type VideoEditorConfig, type VideoEditorImageSegment, type VideoEditorNodeConfig, type VideoEditorSegment, type VideoEditorTextSegment, type VideoEditorVideoSegment, type VideoEditorVisualSegment, VideoElement, type VideoElementProps, type VideoSegment, type VisualSegment, type VisualSegmentUnion, type WordBreak, applyImageDefaults, applyTextDefaults, applyVideoDefaults, areFontsLoaded, buildFontString, calculateAutoWidthDimensions, calculateCropBounds, calculateFitDimensions, calculateLineWidth, canSetAsReference, getBorderRadii, getDependentElements, getFontFamily, getReferenceElementX, getReferenceElementY, hexToRgba, isDynamicCropEnabled, parseHexColor, preloadFonts, resolveElementPositions, useFontsLoaded, useImageLoader, useImagePreloader, useResolvedPositions, wrapText };
+export { type AudioSegment, type BaseEditorConfig, type BaseSegment, type BorderRadiusConfig, type Channel, type CropAxisConfig, type CropBoundary, type CropBounds, DIMENSION_PRESETS, type DimensionPreset, type DimensionPresetKey, type DynamicCropConfig, type EditorConfig, type EditorSegment, FONT_FAMILIES, FONT_URLS, type FitDimensions, type FitMode, type FontType, type FontWeight, type HorizontalAnchor, type HorizontalSelfAnchor, type Hyphenation, IMAGE_DEFAULTS, ImageEditorComposition, type ImageEditorCompositionProps, type ImageEditorConfig, type ImageEditorElement, type ImageEditorNodeConfig, ImageElement, type ImageElementProps, type ImageSegment, type PictureSegment, type PositionResolutionError, type PositionResolutionResult, type RelativePositionConfigX, type RelativePositionConfigY, RenderRoot, type Segment, type SegmentTimelinePosition, type SegmentType, type StaticSegment, TEXT_DEFAULTS, type TextAlignment, type TextDirection, TextElement, type TextElementProps, type TextOverflow, type TextSegment, type TextWrap, type TimeMode, type TimeValue, VIDEO_DEFAULTS, VISUAL_DEFAULTS, type VerticalAlignment, type VerticalAnchor, type VerticalSelfAnchor, type VideoEditorAudioSegment, type VideoEditorBaseSegment, type VideoEditorChannel, VideoEditorComposition, type VideoEditorCompositionProps, type VideoEditorConfig, type VideoEditorImageSegment, type VideoEditorNodeConfig, type VideoEditorSegment, type VideoEditorTextSegment, type VideoEditorVideoSegment, type VideoEditorVisualSegment, VideoElement, type VideoElementProps, type VideoSegment, type VisualSegment, type VisualSegmentUnion, type WordBreak, applyImageDefaults, applyTextDefaults, applyVideoDefaults, areFontsLoaded, buildFontString, calculateAutoWidthDimensions, calculateCropBounds, calculateEstimatedDuration, calculateFitDimensions, calculateLineWidth, calculateTimelineContentEnd, canSetAsReference, defaultOffset, formatTime, generateOverlayId, generateSegmentId, getBaseSegments, getBorderRadii, getDependentElements, getFontFamily, getOverlays, getReferenceElementX, getReferenceElementY, getSegmentTimelinePosition, hexToRgba, isDynamicCropEnabled, isSegmentVisibleAtTime, parseHexColor, parseTime, preloadFonts, resolveElementPositions, useFontsLoaded, useImageLoader, useImagePreloader, useResolvedPositions, wrapText };

package/dist/index.js

@@ -40,17 +40,28 @@ __export(index_exports, {
   buildFontString: () => buildFontString,
   calculateAutoWidthDimensions: () => calculateAutoWidthDimensions,
   calculateCropBounds: () => calculateCropBounds,
+  calculateEstimatedDuration: () => calculateEstimatedDuration,
   calculateFitDimensions: () => calculateFitDimensions,
   calculateLineWidth: () => calculateLineWidth,
+  calculateTimelineContentEnd: () => calculateTimelineContentEnd,
   canSetAsReference: () => canSetAsReference,
+  defaultOffset: () => defaultOffset,
+  formatTime: () => formatTime,
+  generateOverlayId: () => generateOverlayId,
+  generateSegmentId: () => generateSegmentId,
+  getBaseSegments: () => getBaseSegments,
   getBorderRadii: () => getBorderRadii,
   getDependentElements: () => getDependentElements,
   getFontFamily: () => getFontFamily,
+  getOverlays: () => getOverlays,
   getReferenceElementX: () => getReferenceElementX,
   getReferenceElementY: () => getReferenceElementY,
+  getSegmentTimelinePosition: () => getSegmentTimelinePosition,
   hexToRgba: () => hexToRgba,
   isDynamicCropEnabled: () => isDynamicCropEnabled,
+  isSegmentVisibleAtTime: () => isSegmentVisibleAtTime,
   parseHexColor: () => parseHexColor,
+  parseTime: () => parseTime,
   preloadFonts: () => preloadFonts,
   resolveElementPositions: () => resolveElementPositions,
   useFontsLoaded: () => useFontsLoaded,
@@ -1234,9 +1245,9 @@ function calculateSegmentTimings(config, fps) {
       const startFrame = currentFrame + offsetFrames;
       let durationMs;
       if (segment.duration) {
-        durationMs = segment.duration.type === "absolute" ? segment.duration.value : segment.duration.value * (config.duration ?? 1e4);
+        durationMs = segment.duration.type === "absolute" ? segment.duration.value : 5e3;
       } else {
-        durationMs = (config.duration ?? 1e4) - startFrame / fps * 1e3;
+        durationMs = 5e3;
       }
       const durationInFrames = Math.max(1, Math.round(durationMs / 1e3 * fps));
       const endFrame = startFrame + durationInFrames;
@@ -1461,6 +1472,101 @@ function calculateFitDimensions({
   };
 }
 
+// src/utils/timeline.ts
+function defaultOffset(mode = "flexible") {
+  return mode === "flexible" ? { type: "relative", value: 0 } : { type: "absolute", value: 0 };
+}
+function getBaseSegments(channel) {
+  return channel.segments.filter((s) => s.parentId === void 0);
+}
+function getOverlays(channel, parentId) {
+  return channel.segments.filter((s) => s.parentId === (parentId ?? void 0));
+}
+function getSegmentTimelinePosition(segment, baseSegments, channel) {
+  if (segment.parentId) {
+    const parent = channel.segments.find((s) => s.id === segment.parentId);
+    if (parent) {
+      const parentPos = getSegmentTimelinePosition(parent, baseSegments, channel);
+      const relStart = segment.relativeStart ?? 0;
+      const relEnd = segment.relativeEnd ?? 1;
+      return {
+        startMs: parentPos.startMs + parentPos.durationMs * relStart,
+        durationMs: parentPos.durationMs * (relEnd - relStart)
+      };
+    }
+  }
+  const baseIndex = baseSegments.findIndex((s) => s.id === segment.id);
+  let accumulatedTime = 0;
+  for (let i = 0; i < baseIndex; i++) {
+    const prev = baseSegments[i];
+    if (prev) {
+      accumulatedTime += prev.duration?.type === "absolute" ? prev.duration.value : 5e3;
+    }
+  }
+  const startMs = segment.offset.type === "absolute" ? segment.offset.value : accumulatedTime;
+  const durationMs = segment.duration?.type === "absolute" ? segment.duration.value : 5e3;
+  return { startMs, durationMs };
+}
+function isSegmentVisibleAtTime(segment, time, channel) {
+  const baseSegments = getBaseSegments(channel);
+  const { startMs, durationMs } = getSegmentTimelinePosition(segment, baseSegments, channel);
+  const endMs = startMs + durationMs;
+  return time >= startMs && time < endMs;
+}
+function calculateEstimatedDuration(channels) {
+  let maxDuration = 5e3;
+  for (const channel of channels) {
+    let channelTime = 0;
+    for (const segment of channel.segments) {
+      if (segment.parentId) continue;
+      if (segment.offset.type === "absolute") {
+        channelTime = segment.offset.value;
+      } else {
+        channelTime += 5e3;
+      }
+      if (segment.duration?.type === "absolute") {
+        channelTime += segment.duration.value;
+      } else {
+        channelTime += 5e3;
+      }
+    }
+    maxDuration = Math.max(maxDuration, channelTime);
+  }
+  return maxDuration;
+}
+function calculateTimelineContentEnd(channel) {
+  const baseSegments = getBaseSegments(channel);
+  let lastEnd = 0;
+  for (const segment of baseSegments) {
+    const { startMs, durationMs } = getSegmentTimelinePosition(segment, baseSegments, channel);
+    lastEnd = Math.max(lastEnd, startMs + durationMs);
+  }
+  return Math.ceil((lastEnd + 2e3) / 1e3) * 1e3;
+}
+function formatTime(ms) {
+  const totalSeconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const milliseconds = Math.floor(ms % 1e3 / 10);
+  return `${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}.${milliseconds.toString().padStart(2, "0")}`;
+}
+function parseTime(timeStr) {
+  const parts = timeStr.split(":");
+  if (parts.length !== 2) return 0;
+  const [minStr, secPart] = parts;
+  const minutes = parseInt(minStr ?? "0", 10) || 0;
+  const secParts = (secPart ?? "0").split(".");
+  const seconds = parseInt(secParts[0] ?? "0", 10) || 0;
+  const ms = parseInt((secParts[1] ?? "0").padEnd(2, "0").slice(0, 2), 10) * 10 || 0;
+  return (minutes * 60 + seconds) * 1e3 + ms;
+}
+function generateSegmentId() {
+  return `segment-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function generateOverlayId() {
+  return `overlay-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
 // src/hooks/index.ts
 var import_react6 = require("react");
 function useFontsLoaded() {
@@ -1560,7 +1666,6 @@ var defaultVideoProps = {
     width: 1080,
     height: 1920,
     fps: 30,
-    duration: 5e3,
     channels: []
   },
   sources: {},
@@ -1618,17 +1723,28 @@ var RenderRoot = () => {
   buildFontString,
   calculateAutoWidthDimensions,
   calculateCropBounds,
+  calculateEstimatedDuration,
   calculateFitDimensions,
   calculateLineWidth,
+  calculateTimelineContentEnd,
   canSetAsReference,
+  defaultOffset,
+  formatTime,
+  generateOverlayId,
+  generateSegmentId,
+  getBaseSegments,
   getBorderRadii,
   getDependentElements,
   getFontFamily,
+  getOverlays,
   getReferenceElementX,
   getReferenceElementY,
+  getSegmentTimelinePosition,
   hexToRgba,
   isDynamicCropEnabled,
+  isSegmentVisibleAtTime,
   parseHexColor,
+  parseTime,
   preloadFonts,
   resolveElementPositions,
   useFontsLoaded,

package/dist/index.mjs

@@ -1171,9 +1171,9 @@ function calculateSegmentTimings(config, fps) {
       const startFrame = currentFrame + offsetFrames;
       let durationMs;
       if (segment.duration) {
-        durationMs = segment.duration.type === "absolute" ? segment.duration.value : segment.duration.value * (config.duration ?? 1e4);
+        durationMs = segment.duration.type === "absolute" ? segment.duration.value : 5e3;
       } else {
-        durationMs = (config.duration ?? 1e4) - startFrame / fps * 1e3;
+        durationMs = 5e3;
       }
       const durationInFrames = Math.max(1, Math.round(durationMs / 1e3 * fps));
       const endFrame = startFrame + durationInFrames;
@@ -1398,6 +1398,101 @@ function calculateFitDimensions({
   };
 }
 
+// src/utils/timeline.ts
+function defaultOffset(mode = "flexible") {
+  return mode === "flexible" ? { type: "relative", value: 0 } : { type: "absolute", value: 0 };
+}
+function getBaseSegments(channel) {
+  return channel.segments.filter((s) => s.parentId === void 0);
+}
+function getOverlays(channel, parentId) {
+  return channel.segments.filter((s) => s.parentId === (parentId ?? void 0));
+}
+function getSegmentTimelinePosition(segment, baseSegments, channel) {
+  if (segment.parentId) {
+    const parent = channel.segments.find((s) => s.id === segment.parentId);
+    if (parent) {
+      const parentPos = getSegmentTimelinePosition(parent, baseSegments, channel);
+      const relStart = segment.relativeStart ?? 0;
+      const relEnd = segment.relativeEnd ?? 1;
+      return {
+        startMs: parentPos.startMs + parentPos.durationMs * relStart,
+        durationMs: parentPos.durationMs * (relEnd - relStart)
+      };
+    }
+  }
+  const baseIndex = baseSegments.findIndex((s) => s.id === segment.id);
+  let accumulatedTime = 0;
+  for (let i = 0; i < baseIndex; i++) {
+    const prev = baseSegments[i];
+    if (prev) {
+      accumulatedTime += prev.duration?.type === "absolute" ? prev.duration.value : 5e3;
+    }
+  }
+  const startMs = segment.offset.type === "absolute" ? segment.offset.value : accumulatedTime;
+  const durationMs = segment.duration?.type === "absolute" ? segment.duration.value : 5e3;
+  return { startMs, durationMs };
+}
+function isSegmentVisibleAtTime(segment, time, channel) {
+  const baseSegments = getBaseSegments(channel);
+  const { startMs, durationMs } = getSegmentTimelinePosition(segment, baseSegments, channel);
+  const endMs = startMs + durationMs;
+  return time >= startMs && time < endMs;
+}
+function calculateEstimatedDuration(channels) {
+  let maxDuration = 5e3;
+  for (const channel of channels) {
+    let channelTime = 0;
+    for (const segment of channel.segments) {
+      if (segment.parentId) continue;
+      if (segment.offset.type === "absolute") {
+        channelTime = segment.offset.value;
+      } else {
+        channelTime += 5e3;
+      }
+      if (segment.duration?.type === "absolute") {
+        channelTime += segment.duration.value;
+      } else {
+        channelTime += 5e3;
+      }
+    }
+    maxDuration = Math.max(maxDuration, channelTime);
+  }
+  return maxDuration;
+}
+function calculateTimelineContentEnd(channel) {
+  const baseSegments = getBaseSegments(channel);
+  let lastEnd = 0;
+  for (const segment of baseSegments) {
+    const { startMs, durationMs } = getSegmentTimelinePosition(segment, baseSegments, channel);
+    lastEnd = Math.max(lastEnd, startMs + durationMs);
+  }
+  return Math.ceil((lastEnd + 2e3) / 1e3) * 1e3;
+}
+function formatTime(ms) {
+  const totalSeconds = Math.floor(ms / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  const milliseconds = Math.floor(ms % 1e3 / 10);
+  return `${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}.${milliseconds.toString().padStart(2, "0")}`;
+}
+function parseTime(timeStr) {
+  const parts = timeStr.split(":");
+  if (parts.length !== 2) return 0;
+  const [minStr, secPart] = parts;
+  const minutes = parseInt(minStr ?? "0", 10) || 0;
+  const secParts = (secPart ?? "0").split(".");
+  const seconds = parseInt(secParts[0] ?? "0", 10) || 0;
+  const ms = parseInt((secParts[1] ?? "0").padEnd(2, "0").slice(0, 2), 10) * 10 || 0;
+  return (minutes * 60 + seconds) * 1e3 + ms;
+}
+function generateSegmentId() {
+  return `segment-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+function generateOverlayId() {
+  return `overlay-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
 // src/hooks/index.ts
 import { useEffect, useState, useMemo as useMemo6 } from "react";
 function useFontsLoaded() {
@@ -1497,7 +1592,6 @@ var defaultVideoProps = {
     width: 1080,
     height: 1920,
     fps: 30,
-    duration: 5e3,
     channels: []
   },
   sources: {},
@@ -1554,17 +1648,28 @@ export {
   buildFontString,
   calculateAutoWidthDimensions,
   calculateCropBounds,
+  calculateEstimatedDuration,
   calculateFitDimensions,
   calculateLineWidth,
+  calculateTimelineContentEnd,
   canSetAsReference,
+  defaultOffset,
+  formatTime,
+  generateOverlayId,
+  generateSegmentId,
+  getBaseSegments,
   getBorderRadii,
   getDependentElements,
   getFontFamily,
+  getOverlays,
   getReferenceElementX,
   getReferenceElementY,
+  getSegmentTimelinePosition,
   hexToRgba,
   isDynamicCropEnabled,
+  isSegmentVisibleAtTime,
   parseHexColor,
+  parseTime,
   preloadFonts,
   resolveElementPositions,
   useFontsLoaded,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugcinc-render",
-  "version": "1.3.14",
+  "version": "1.5.0",
   "description": "Unified rendering package for UGC Inc - shared types, components, and compositions for pixel-perfect client/server rendering",
   "main": "dist/index.js",
   "module": "dist/index.mjs",