@twick/timeline 0.14.2 → 0.14.4

package/dist/index.js

@@ -6,13 +6,19 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
   const PLAYER_STATE = {
+    /** Player is refreshing/reloading content */
     REFRESH: "Refresh",
+    /** Player is actively playing content */
     PLAYING: "Playing",
+    /** Player is paused */
     PAUSED: "Paused"
   };
   const CAPTION_STYLE = {
+    /** Highlights background of each word */
     WORD_BG_HIGHLIGHT: "highlight_bg",
+    /** Animates text word by word */
     WORD_BY_WORD: "word_by_word",
+    /** Animates text word by word with background highlighting */
     WORD_BY_WORD_WITH_BG: "word_by_word_with_bg"
   };
   const CAPTION_STYLE_OPTIONS = {
@@ -30,34 +36,54 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     }
   };
   const CAPTION_FONT = {
+    /** Font size in pixels */
     size: 40
   };
   const CAPTION_COLOR = {
+    /** Text color in hex format */
     text: "#ffffff",
+    /** Highlight color in hex format */
     highlight: "#ff4081",
+    /** Background color in hex format */
     bgColor: "#8C52FF"
   };
   const WORDS_PER_PHRASE = 4;
   const TIMELINE_ACTION = {
+    /** No action being performed */
     NONE: "none",
+    /** Setting the player state (play/pause) */
     SET_PLAYER_STATE: "setPlayerState",
+    /** Updating player data */
     UPDATE_PLAYER_DATA: "updatePlayerData",
+    /** Player has been updated */
     ON_PLAYER_UPDATED: "onPlayerUpdated"
   };
   const TIMELINE_ELEMENT_TYPE = {
+    /** Video element type */
     VIDEO: "video",
+    /** Caption element type */
     CAPTION: "caption",
+    /** Image element type */
     IMAGE: "image",
+    /** Audio element type */
     AUDIO: "audio",
+    /** Text element type */
     TEXT: "text",
+    /** Rectangle element type */
     RECT: "rect",
+    /** Circle element type */
     CIRCLE: "circle",
+    /** Icon element type */
     ICON: "icon"
   };
   const PROCESS_STATE = {
+    /** Process is idle */
     IDLE: "Idle",
+    /** Process is currently running */
     PROCESSING: "Processing",
+    /** Process has completed successfully */
     COMPLETED: "Completed",
+    /** Process has failed */
     FAILED: "Failed"
   };
   const imageDimensionsCache = {};
@@ -458,7 +484,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.type = type;
       this.props = {
         x: 0,
-        y: 0
+        y: 0,
+        opacity: 1,
+        rotation: 0
       };
     }
     getId() {
@@ -495,6 +523,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         y: ((_b = this.props) == null ? void 0 : _b.y) ?? 0
       };
     }
+    getRotation() {
+      return this.props.rotation ?? 0;
+    }
+    getOpacity() {
+      return this.props.opacity ?? 1;
+    }
     setId(id) {
       this.id = id;
       return this;
@@ -528,6 +562,14 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.props.y = position.y;
       return this;
     }
+    setRotation(rotation) {
+      this.props.rotation = rotation;
+      return this;
+    }
+    setOpacity(opacity) {
+      this.props.opacity = opacity;
+      return this;
+    }
     setProps(props) {
       this.props = structuredClone(props);
       return this;
@@ -1016,13 +1058,35 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     }
   }
   class IconElement extends TrackElement {
-    constructor(src, size) {
+    constructor(src, size, fill = "#866bbf") {
       super(TIMELINE_ELEMENT_TYPE.ICON);
       this.props = {
         src,
+        fill,
         size
       };
     }
+    getSrc() {
+      return this.props.src;
+    }
+    getFill() {
+      return this.props.fill;
+    }
+    getSize() {
+      return this.props.size;
+    }
+    setSrc(src) {
+      this.props.src = src;
+      return this;
+    }
+    setFill(fill) {
+      this.props.fill = fill;
+      return this;
+    }
+    setSize(size) {
+      this.props.size = size;
+      return this;
+    }
     accept(visitor) {
       return visitor.visitIconElement(this);
     }
@@ -1032,7 +1096,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       super(TIMELINE_ELEMENT_TYPE.CIRCLE);
       this.props = {
         radius,
-        fill
+        fill,
+        strokeColor: fill,
+        lineWidth: 1
       };
     }
     getFill() {
@@ -1041,6 +1107,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     getRadius() {
       return this.props.radius;
     }
+    getStrokeColor() {
+      return this.props.strokeColor || this.props.fill;
+    }
+    getLineWidth() {
+      return this.props.lineWidth ?? 0;
+    }
     setFill(fill) {
       this.props.fill = fill;
       return this;
@@ -1049,6 +1121,14 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.props.radius = radius;
       return this;
     }
+    setStrokeColor(strokeColor) {
+      this.props.strokeColor = strokeColor;
+      return this;
+    }
+    setLineWidth(lineWidth) {
+      this.props.lineWidth = lineWidth;
+      return this;
+    }
     accept(visitor) {
       return visitor.visitCircleElement(this);
     }
@@ -1059,18 +1139,48 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.props = {
         width: size.width,
         height: size.height,
-        fill
+        fill,
+        radius: 0,
+        strokeColor: fill,
+        lineWidth: 1
       };
     }
+    getFill() {
+      return this.props.fill;
+    }
     setFill(fill) {
       this.props.fill = fill;
       return this;
     }
+    getSize() {
+      return { width: this.props.width, height: this.props.height };
+    }
+    getCornerRadius() {
+      return this.props.radius;
+    }
+    getStrokeColor() {
+      return this.props.strokeColor || this.props.fill;
+    }
+    getLineWidth() {
+      return this.props.lineWidth ?? 0;
+    }
     setSize(size) {
       this.props.width = size.width;
       this.props.height = size.height;
       return this;
     }
+    setCornerRadius(cornerRadius) {
+      this.props.radius = cornerRadius;
+      return this;
+    }
+    setStrokeColor(strokeColor) {
+      this.props.strokeColor = strokeColor;
+      return this;
+    }
+    setLineWidth(lineWidth) {
+      this.props.lineWidth = lineWidth;
+      return this;
+    }
     accept(visitor) {
       return visitor.visitRectElement(this);
     }
@@ -1079,6 +1189,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     constructor(name) {
       __publicField(this, "name");
       __publicField(this, "interval");
+      __publicField(this, "duration");
       __publicField(this, "intensity");
       __publicField(this, "animate");
       __publicField(this, "mode");
@@ -1091,6 +1202,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     getInterval() {
       return this.interval;
     }
+    getDuration() {
+      return this.duration;
+    }
     getIntensity() {
       return this.intensity;
     }
@@ -1107,6 +1221,10 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.interval = interval;
       return this;
     }
+    setDuration(duration) {
+      this.duration = duration;
+      return this;
+    }
     setIntensity(intensity) {
       this.intensity = intensity;
       return this;
@@ -1127,6 +1245,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       return {
         name: this.name,
         interval: this.interval,
+        duration: this.duration,
         intensity: this.intensity,
         animate: this.animate,
         mode: this.mode,
@@ -1136,6 +1255,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     static fromJSON(json) {
       const animation = new ElementAnimation(json.name);
       animation.setInterval(json.interval);
+      animation.setDuration(json.duration);
       animation.setIntensity(json.intensity);
       animation.setAnimate(json.animate);
       animation.setMode(json.mode);
@@ -1221,7 +1341,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       return {
         name: this.name,
         delay: this.delay,
-        duration: this.duration,
+        duration: this.duration ?? 1,
         bufferTime: this.bufferTime
       };
     }
@@ -1289,11 +1409,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       return captionElement;
     }
     static deserializeIconElement(json) {
-      var _a, _b;
-      const size = ((_a = json.props) == null ? void 0 : _a.size) ? { width: json.props.size[0], height: json.props.size[1] } : { width: 0, height: 0 };
+      var _a, _b, _c;
+      const size = ((_a = json.props) == null ? void 0 : _a.size) ?? { width: 100, height: 100 };
       const iconElement = new IconElement(
         ((_b = json.props) == null ? void 0 : _b.src) || "",
-        size
+        size,
+        (_c = json.props) == null ? void 0 : _c.fill
       );
       ElementDeserializer.deserializeBaseElement(iconElement, json);
       return iconElement;
@@ -1529,10 +1650,6 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       const basicValidation = this.validateBasicProperties(element);
       const errors = [...basicValidation.errors];
       const warnings = [...basicValidation.warnings];
-      const props = element.getProps();
-      if (!(props == null ? void 0 : props.icon)) {
-        errors.push("Icon element must have an icon name");
-      }
       return { errors, warnings };
     }
     validateCircleElement(element) {
@@ -1684,7 +1801,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     }
   }
   class Track {
-    constructor(name, id) {
+    /**
+     * Creates a new Track instance.
+     * 
+     * @param name - The display name for the track
+     * @param type - The type of the track
+     * @param id - Optional unique identifier (auto-generated if not provided)
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Video Track");
+     * const trackWithId = new Track("Audio Track", "element", "video-track-1");
+     * ```
+     */
+    constructor(name, type = "element", id) {
       __publicField(this, "id");
       __publicField(this, "name");
       __publicField(this, "type");
@@ -1692,71 +1822,215 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       __publicField(this, "validator");
       this.name = name;
       this.id = id ?? `t-${generateShortUuid}`;
-      this.type = "element";
+      this.type = type;
       this.elements = [];
       this.validator = new ElementValidator();
     }
     /**
-     * Create a friend instance for explicit access to protected methods
-     * This implements the Friend Class Pattern
-     * @returns TrackFriend instance
+     * Creates a friend instance for explicit access to protected methods.
+     * This implements the Friend Class Pattern to allow controlled access
+     * to protected methods while maintaining encapsulation.
+     * 
+     * @returns TrackFriend instance that can access protected methods
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const friend = track.createFriend();
+     * 
+     * // Use friend to add elements
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * friend.addElement(element);
+     * ```
      */
     createFriend() {
       return new TrackFriend(this);
     }
     /**
-     * Friend method to add element (called by TrackFriend)
-     * @param element The element to add
-     * @param skipValidation If true, skips validation
+     * Friend method to add element (called by TrackFriend).
+     * Provides controlled access to the protected addElement method.
+     * 
+     * @param element - The element to add to the track
+     * @param skipValidation - If true, skips validation (use with caution)
      * @returns true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const friend = track.createFriend();
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * const success = track.addElementViaFriend(element);
+     * // success = true if element was added successfully
+     * ```
      */
     addElementViaFriend(element, skipValidation = false) {
       return this.addElement(element, skipValidation);
     }
     /**
-     * Friend method to remove element (called by TrackFriend)
-     * @param element The element to remove
+     * Friend method to remove element (called by TrackFriend).
+     * Provides controlled access to the protected removeElement method.
+     * 
+     * @param element - The element to remove from the track
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * track.removeElementViaFriend(element);
+     * // Element is removed from the track
+     * ```
      */
     removeElementViaFriend(element) {
       this.removeElement(element);
     }
     /**
-     * Friend method to update element (called by TrackFriend)
-     * @param element The element to update
+     * Friend method to update element (called by TrackFriend).
+     * Provides controlled access to the protected updateElement method.
+     * 
+     * @param element - The updated element to replace the existing one
      * @returns true if element was updated successfully
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * // Update the element
+     * element.setEnd(15);
+     * const success = track.updateElementViaFriend(element);
+     * // success = true if element was updated successfully
+     * ```
      */
     updateElementViaFriend(element) {
       return this.updateElement(element);
     }
+    /**
+     * Gets the unique identifier of the track.
+     * 
+     * @returns The track's unique ID string
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track", "element", "track-123");
+     * const id = track.getId(); // "track-123"
+     * ```
+     */
     getId() {
       return this.id;
     }
+    /**
+     * Gets the display name of the track.
+     * 
+     * @returns The track's display name
+     * 
+     * @example
+     * ```js
+     * const track = new Track("Video Track");
+     * const name = track.getName(); // "Video Track"
+     * ```
+     */
     getName() {
       return this.name;
     }
+    /**
+     * Gets the type of the track.
+     * 
+     * @returns The track's type string
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const type = track.getType(); // "element"
+     * ```
+     */
     getType() {
       return this.type;
     }
+    /**
+     * Gets a read-only array of all elements in the track.
+     * Returns a copy of the elements array to prevent external modification.
+     * 
+     * @returns Read-only array of track elements
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const elements = track.getElements();
+     * // elements is a read-only array of TrackElement instances
+     * 
+     * elements.forEach(element => {
+     *   console.log(`Element: ${element.getId()}, Duration: ${element.getEnd() - element.getStart()}`);
+     * });
+     * ```
+     */
     getElements() {
       return [...this.elements];
     }
     /**
-     * Validates an element
-     * @param element The element to validate
+     * Validates a single element using the track's validator.
+     * Checks if the element meets all validation requirements.
+     * 
+     * @param element - The element to validate
      * @returns true if valid, throws ValidationError if invalid
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * try {
+     *   const isValid = track.validateElement(element);
+     *   console.log('Element is valid:', isValid);
+     * } catch (error) {
+     *   if (error instanceof ValidationError) {
+     *     console.log('Validation failed:', error.errors);
+     *   }
+     * }
+     * ```
      */
     validateElement(element) {
       return element.accept(this.validator);
     }
+    /**
+     * Gets the total duration of the track.
+     * Calculates the duration based on the end time of the last element.
+     * 
+     * @returns The total duration of the track in seconds
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const duration = track.getTrackDuration(); // 0 if no elements
+     * 
+     * // After adding elements
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 30 });
+     * track.createFriend().addElement(element);
+     * const newDuration = track.getTrackDuration(); // 30
+     * ```
+     */
     getTrackDuration() {
       var _a;
       return ((_a = this.elements) == null ? void 0 : _a.length) ? this.elements[this.elements.length - 1].getEnd() : 0;
     }
     /**
-     * Adds an element to the track with validation
-     * @param element The element to add
-     * @param skipValidation If true, skips validation (use with caution)
+     * Adds an element to the track with validation.
+     * Protected method that should be accessed through TrackFriend.
+     * 
+     * @param element - The element to add to the track
+     * @param skipValidation - If true, skips validation (use with caution)
      * @returns true if element was added successfully, throws ValidationError if validation fails
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * const success = friend.addElement(element);
+     * ```
      */
     addElement(element, skipValidation = false) {
       element.setTrackId(this.id);
@@ -1778,6 +2052,22 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return false;
     }
+    /**
+     * Removes an element from the track.
+     * Protected method that should be accessed through TrackFriend.
+     * 
+     * @param element - The element to remove from the track
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * friend.removeElement(element);
+     * ```
+     */
     removeElement(element) {
       const index2 = this.elements.findIndex((e2) => e2.getId() === element.getId());
       if (index2 !== -1) {
@@ -1785,9 +2075,22 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
     }
     /**
-     * Updates an element in the track with validation
-     * @param element The element to update
+     * Updates an element in the track with validation.
+     * Protected method that should be accessed through TrackFriend.
+     * 
+     * @param element - The updated element to replace the existing one
      * @returns true if element was updated successfully, throws ValidationError if validation fails
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * 
+     * // Use friend to access this protected method
+     * const friend = track.createFriend();
+     * element.setEnd(15);
+     * const success = friend.updateElement(element);
+     * ```
      */
     updateElement(element) {
       try {
@@ -1809,14 +2112,55 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return false;
     }
+    /**
+     * Finds an element in the track by its ID.
+     * 
+     * @param id - The unique identifier of the element to find
+     * @returns The found element or undefined if not found
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * track.createFriend().addElement(element);
+     * 
+     * const foundElement = track.getElementById(element.getId());
+     * // foundElement is the same element instance
+     * ```
+     */
     getElementById(id) {
       const element = this.elements.find((e2) => e2.getId() === id);
       if (!element) return void 0;
       return element;
     }
     /**
-     * Validates all elements in the track and returns combined result and per-element status
+     * Validates all elements in the track and returns combined result and per-element status.
+     * Provides detailed validation information for each element including errors and warnings.
+     * 
      * @returns Object with overall isValid and array of per-element validation results
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element1 = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * const element2 = new TextElement({ text: "Hello", start: 5, end: 15 });
+     * 
+     * track.createFriend().addElement(element1);
+     * track.createFriend().addElement(element2);
+     * 
+     * const validation = track.validateAllElements();
+     * console.log('Overall valid:', validation.isValid);
+     * 
+     * validation.results.forEach(result => {
+     *   console.log(`Element ${result.element.getId()}: ${result.isValid ? 'Valid' : 'Invalid'}`);
+     *   if (result.errors) {
+     *     console.log('Errors:', result.errors);
+     *   }
+     *   if (result.warnings) {
+     *     console.log('Warnings:', result.warnings);
+     *   }
+     * });
+     * ```
      */
     validateAllElements() {
       let validResult = true;
@@ -1846,6 +2190,30 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       });
       return { isValid: validResult, results };
     }
+    /**
+     * Serializes the track and all its elements to JSON format.
+     * Converts the track structure to a format that can be stored or transmitted.
+     * 
+     * @returns TrackJSON object representing the track and its elements
+     * 
+     * @example
+     * ```js
+     * const track = new Track("My Track");
+     * const element = new VideoElement({ src: "video.mp4", start: 0, end: 10 });
+     * track.createFriend().addElement(element);
+     * 
+     * const trackData = track.serialize();
+     * // trackData = {
+     * //   id: "t-abc123",
+     * //   name: "My Track",
+     * //   type: "element",
+     * //   elements: [{ ... }]
+     * // }
+     * 
+     * // Save to localStorage
+     * localStorage.setItem('track-data', JSON.stringify(trackData));
+     * ```
+     */
     serialize() {
       const serializer = new ElementSerializer();
       return {
@@ -1857,8 +2225,37 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         )
       };
     }
+    /**
+     * Creates a Track instance from JSON data.
+     * Static factory method for deserializing track data.
+     * 
+     * @param json - JSON object containing track data
+     * @returns New Track instance with loaded data
+     * 
+     * @example
+     * ```js
+     * const trackData = {
+     *   id: "t-abc123",
+     *   name: "My Track",
+     *   type: "element",
+     *   elements: [
+     *     {
+     *       id: "e-def456",
+     *       type: "video",
+     *       src: "video.mp4",
+     *       start: 0,
+     *       end: 10
+     *     }
+     *   ]
+     * };
+     * 
+     * const track = Track.fromJSON(trackData);
+     * console.log(track.getName()); // "My Track"
+     * console.log(track.getElements().length); // 1
+     * ```
+     */
     static fromJSON(json) {
-      const track = new Track(json.name, json.id);
+      const track = new Track(json.name, json.type ?? "element", json.id);
       track.type = json.type;
       track.elements = (json.elements || []).map(ElementDeserializer.fromJSON);
       return track;
@@ -1936,12 +2333,37 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   let TimelineContextStore = _TimelineContextStore;
   const timelineContextStore = TimelineContextStore.getInstance();
   class ElementAdder {
+    /**
+     * Creates a new ElementAdder instance for the specified track.
+     *
+     * @param track - The track to add elements to
+     * 
+     * @example
+     * ```js
+     * const adder = new ElementAdder(track);
+     * const success = await adder.visitVideoElement(videoElement);
+     * ```
+     */
     constructor(track) {
       __publicField(this, "track");
       __publicField(this, "trackFriend");
       this.track = track;
       this.trackFriend = track.createFriend();
     }
+    /**
+     * Adds a video element to the track.
+     * Updates video metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The video element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitVideoElement(videoElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitVideoElement(element) {
       await element.updateVideoMeta();
       const elements = this.track.getElements();
@@ -1954,6 +2376,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an audio element to the track.
+     * Updates audio metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The audio element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitAudioElement(audioElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitAudioElement(element) {
       await element.updateAudioMeta();
       const elements = this.track.getElements();
@@ -1966,6 +2402,20 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an image element to the track.
+     * Updates image metadata and calculates appropriate start/end times
+     * based on existing track elements.
+     *
+     * @param element - The image element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitImageElement(imageElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitImageElement(element) {
       await element.updateImageMeta();
       const elements = this.track.getElements();
@@ -1978,6 +2428,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a text element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The text element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitTextElement(textElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitTextElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -1989,6 +2452,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a caption element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The caption element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitCaptionElement(captionElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitCaptionElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2000,6 +2476,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds an icon element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The icon element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitIconElement(iconElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitIconElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2011,6 +2500,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a circle element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The circle element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitCircleElement(circleElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitCircleElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2022,6 +2524,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       }
       return this.trackFriend.addElement(element);
     }
+    /**
+     * Adds a rectangle element to the track.
+     * Calculates appropriate start/end times based on existing track elements.
+     *
+     * @param element - The rectangle element to add
+     * @returns Promise resolving to true if element was added successfully
+     * 
+     * @example
+     * ```js
+     * const success = await adder.visitRectElement(rectElement);
+     * // success = true if element was added successfully
+     * ```
+     */
     async visitRectElement(element) {
       const elements = this.track.getElements();
       const lastEndtime = (elements == null ? void 0 : elements.length) ? elements[elements.length - 1].getEnd() : 0;
@@ -2162,7 +2677,8 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     visitIconElement(element) {
       const clonedElement = new IconElement(
         element.getProps().src,
-        element.getProps().size
+        element.getProps().size,
+        element.getProps().fill
       );
       this.cloneElementProperties(element, clonedElement);
       return clonedElement;
@@ -2351,10 +2867,10 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.context.updateChangeLog();
       return updatedTimelineData;
     }
-    addTrack(name) {
+    addTrack(name, type = "element") {
       const prevTimelineData = this.getTimelineData();
       const id = `t-${generateShortUuid()}`;
-      const track = new Track(name, id);
+      const track = new Track(name, type, id);
       const updatedTimelines = [...(prevTimelineData == null ? void 0 : prevTimelineData.tracks) || [], track];
       this.setTimelineData(updatedTimelines);
       return track;
@@ -2441,12 +2957,12 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     /**
      * Update an element in a specific track using the visitor pattern
      * @param element The updated element
-     * @returns boolean true if element was updated successfully
+     * @returns TrackElement the updated element
      */
     updateElement(element) {
       const track = this.getTrackById(element.getTrackId());
       if (!track) {
-        return false;
+        return element;
       }
       try {
         const elementUpdater = new ElementUpdater(track);
@@ -2457,9 +2973,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
             this.setTimelineData(currentData.tracks);
           }
         }
-        return result;
+        return element;
       } catch (error) {
-        return false;
+        return element;
       }
     }
     /**
@@ -7272,6 +7788,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   const TimelineProviderInner = ({
     contextId,
     children,
+    resolution,
     initialData
   }) => {
     const [timelineAction, setTimelineActionState] = React.useState({
@@ -7281,6 +7798,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
     const [selectedItem, setSelectedItem] = React.useState(
       null
     );
+    const [videoResolution, setVideoResolution] = React.useState(resolution ?? { width: 720, height: 1280 });
     const [totalDuration, setTotalDuration] = React.useState(0);
     const [changeLog, setChangeLog] = React.useState(0);
     const undoRedoContext = useUndoRedo();
@@ -7335,9 +7853,11 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       timelineAction,
       totalDuration,
       changeLog,
+      videoResolution,
       present: undoRedoContext.present,
       canUndo: undoRedoContext.canUndo,
       canRedo: undoRedoContext.canRedo,
+      setVideoResolution,
       setSelectedItem,
       setTimelineAction,
       editor
@@ -7348,6 +7868,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
   const TimelineProvider = ({
     contextId,
     children,
+    resolution = { width: 720, height: 1280 },
     initialData,
     undoRedoPersistenceKey,
     maxHistorySize
@@ -7369,6 +7890,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
             children: /* @__PURE__ */ jsxRuntime.jsx(
               TimelineProviderInner,
               {
+                resolution,
                 initialData,
                 contextId,
                 undoRedoPersistenceKey,