@twick/timeline 0.14.2 → 0.14.4

package/dist/index.mjs

@@ -4,13 +4,19 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 import { jsx } from "react/jsx-runtime";
 import React, { useState, createContext, useContext, useRef, useMemo, useEffect } from "react";
 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 = {
@@ -28,34 +34,54 @@ const CAPTION_STYLE_OPTIONS = {
   }
 };
 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 = {};
@@ -456,7 +482,9 @@ class TrackElement {
     this.type = type;
     this.props = {
       x: 0,
-      y: 0
+      y: 0,
+      opacity: 1,
+      rotation: 0
     };
   }
   getId() {
@@ -493,6 +521,12 @@ class TrackElement {
       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;
@@ -526,6 +560,14 @@ class TrackElement {
     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;
@@ -1014,13 +1056,35 @@ class CaptionElement extends TrackElement {
   }
 }
 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);
   }
@@ -1030,7 +1094,9 @@ class CircleElement extends TrackElement {
     super(TIMELINE_ELEMENT_TYPE.CIRCLE);
     this.props = {
       radius,
-      fill
+      fill,
+      strokeColor: fill,
+      lineWidth: 1
     };
   }
   getFill() {
@@ -1039,6 +1105,12 @@ class CircleElement extends TrackElement {
   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;
@@ -1047,6 +1119,14 @@ class CircleElement extends TrackElement {
     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);
   }
@@ -1057,18 +1137,48 @@ class RectElement extends TrackElement {
     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);
   }
@@ -1077,6 +1187,7 @@ class ElementAnimation {
   constructor(name) {
     __publicField(this, "name");
     __publicField(this, "interval");
+    __publicField(this, "duration");
     __publicField(this, "intensity");
     __publicField(this, "animate");
     __publicField(this, "mode");
@@ -1089,6 +1200,9 @@ class ElementAnimation {
   getInterval() {
     return this.interval;
   }
+  getDuration() {
+    return this.duration;
+  }
   getIntensity() {
     return this.intensity;
   }
@@ -1105,6 +1219,10 @@ class ElementAnimation {
     this.interval = interval;
     return this;
   }
+  setDuration(duration) {
+    this.duration = duration;
+    return this;
+  }
   setIntensity(intensity) {
     this.intensity = intensity;
     return this;
@@ -1125,6 +1243,7 @@ class ElementAnimation {
     return {
       name: this.name,
       interval: this.interval,
+      duration: this.duration,
       intensity: this.intensity,
       animate: this.animate,
       mode: this.mode,
@@ -1134,6 +1253,7 @@ class ElementAnimation {
   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);
@@ -1219,7 +1339,7 @@ class ElementTextEffect {
     return {
       name: this.name,
       delay: this.delay,
-      duration: this.duration,
+      duration: this.duration ?? 1,
       bufferTime: this.bufferTime
     };
   }
@@ -1287,11 +1407,12 @@ class ElementDeserializer {
     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;
@@ -1527,10 +1648,6 @@ class ElementValidator {
     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) {
@@ -1682,7 +1799,20 @@ class TrackFriend {
   }
 }
 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");
@@ -1690,71 +1820,215 @@ class Track {
     __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);
@@ -1776,6 +2050,22 @@ class Track {
     }
     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 index = this.elements.findIndex((e2) => e2.getId() === element.getId());
     if (index !== -1) {
@@ -1783,9 +2073,22 @@ class Track {
     }
   }
   /**
-   * 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 {
@@ -1807,14 +2110,55 @@ class Track {
     }
     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;
@@ -1844,6 +2188,30 @@ class Track {
     });
     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 {
@@ -1855,8 +2223,37 @@ class Track {
       )
     };
   }
+  /**
+   * 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;
@@ -1934,12 +2331,37 @@ __publicField(_TimelineContextStore, "instance");
 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();
@@ -1952,6 +2374,20 @@ class ElementAdder {
     }
     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();
@@ -1964,6 +2400,20 @@ class ElementAdder {
     }
     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();
@@ -1976,6 +2426,19 @@ class ElementAdder {
     }
     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;
@@ -1987,6 +2450,19 @@ class ElementAdder {
     }
     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;
@@ -1998,6 +2474,19 @@ class ElementAdder {
     }
     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;
@@ -2009,6 +2498,19 @@ class ElementAdder {
     }
     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;
@@ -2020,6 +2522,19 @@ class ElementAdder {
     }
     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;
@@ -2160,7 +2675,8 @@ class ElementCloner {
   visitIconElement(element) {
     const clonedElement = new IconElement(
       element.getProps().src,
-      element.getProps().size
+      element.getProps().size,
+      element.getProps().fill
     );
     this.cloneElementProperties(element, clonedElement);
     return clonedElement;
@@ -2349,10 +2865,10 @@ class TimelineEditor {
     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;
@@ -2439,12 +2955,12 @@ class TimelineEditor {
   /**
    * 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);
@@ -2455,9 +2971,9 @@ class TimelineEditor {
           this.setTimelineData(currentData.tracks);
         }
       }
-      return result;
+      return element;
     } catch (error) {
-      return false;
+      return element;
     }
   }
   /**
@@ -7270,6 +7786,7 @@ const TimelineContext = createContext(
 const TimelineProviderInner = ({
   contextId,
   children,
+  resolution,
   initialData
 }) => {
   const [timelineAction, setTimelineActionState] = useState({
@@ -7279,6 +7796,7 @@ const TimelineProviderInner = ({
   const [selectedItem, setSelectedItem] = useState(
     null
   );
+  const [videoResolution, setVideoResolution] = useState(resolution ?? { width: 720, height: 1280 });
   const [totalDuration, setTotalDuration] = useState(0);
   const [changeLog, setChangeLog] = useState(0);
   const undoRedoContext = useUndoRedo();
@@ -7333,9 +7851,11 @@ const TimelineProviderInner = ({
     timelineAction,
     totalDuration,
     changeLog,
+    videoResolution,
     present: undoRedoContext.present,
     canUndo: undoRedoContext.canUndo,
     canRedo: undoRedoContext.canRedo,
+    setVideoResolution,
     setSelectedItem,
     setTimelineAction,
     editor
@@ -7346,6 +7866,7 @@ const TimelineProviderInner = ({
 const TimelineProvider = ({
   contextId,
   children,
+  resolution = { width: 720, height: 1280 },
   initialData,
   undoRedoPersistenceKey,
   maxHistorySize
@@ -7367,6 +7888,7 @@ const TimelineProvider = ({
           children: /* @__PURE__ */ jsx(
             TimelineProviderInner,
             {
+              resolution,
               initialData,
               contextId,
               undoRedoPersistenceKey,