@shotstack/shotstack-studio 2.0.0-beta.16 → 2.0.0-beta.17

package/dist/index.d.ts

@@ -375,7 +375,9 @@ declare interface ClipStats {
 export declare class ClipToolbar extends BaseToolbar {
     private startControl;
     private lengthControl;
+    private editChangedListener;
     mount(parent: HTMLElement): void;
+    private setupEventListeners;
     private mountComponents;
     private applyTimingUpdate;
     protected syncState(): void;
@@ -424,6 +426,24 @@ declare type CommandContext = {
     setOutputFps(fps: number): void;
     getTimelineBackground(): string;
     setTimelineBackground(color: string): void;
+    getDocument(): EditDocument | null;
+    /** Update a clip's properties in the document (source of truth) */
+    documentUpdateClip(trackIdx: number, clipIdx: number, updates: Partial<DocumentClipType>): void;
+    /** Add a clip to the document, returns the added clip */
+    documentAddClip(trackIdx: number, clip: DocumentClipType, clipIdx?: number): DocumentClipType;
+    /** Remove a clip from the document, returns the removed clip or null */
+    documentRemoveClip(trackIdx: number, clipIdx: number): DocumentClipType | null;
+    /** Derive runtime Player state from document clip (applies document data to Player) */
+    derivePlayerFromDocument(trackIdx: number, clipIdx: number): void;
+    /**
+     * Build resolution context for a clip at the given position.
+     * Extracts all dependencies upfront so resolution can be pure.
+     *
+     * @param trackIdx - Track index
+     * @param clipIdx - Clip index on that track
+     * @returns Context with previousClipEnd, timelineEnd, intrinsicDuration
+     */
+    buildResolutionContext(trackIdx: number, clipIdx: number): ResolutionContext;
 };
 
 export declare class Controls {
@@ -533,6 +553,8 @@ export declare const DestinationSchema: z.ZodUnion<readonly [z.ZodIntersection<z
     }, z.core.$strip>>;
 }, z.core.$strip>>]>;
 
+declare type DocumentClipType = Clip;
+
 export declare class Edit extends Entity {
     private static readonly ZIndexPadding;
     /**
@@ -952,6 +974,185 @@ declare type EditCommand = {
 /** Alias for Edit type to avoid conflicts with SDK's Edit class */
 export declare type EditConfig = Edit_2;
 
+declare class EditDocument {
+    private data;
+    constructor(edit: Edit_2);
+    /**
+     * Get the raw timeline configuration
+     */
+    getTimeline(): Edit_2["timeline"];
+    /**
+     * Get timeline background color
+     */
+    getBackground(): string | undefined;
+    /**
+     * Get all tracks (raw, unresolved)
+     */
+    getTracks(): Track[];
+    /**
+     * Get a specific track by index
+     */
+    getTrack(index: number): Track | null;
+    /**
+     * Get total number of tracks
+     */
+    getTrackCount(): number;
+    /**
+     * Get soundtrack configuration
+     */
+    getSoundtrack(): Soundtrack | undefined;
+    /**
+     * Get a specific clip by track and clip index
+     */
+    getClip(trackIndex: number, clipIndex: number): Clip | null;
+    /**
+     * Get all clips in a track
+     */
+    getClipsInTrack(trackIndex: number): Clip[];
+    /**
+     * Get total number of clips across all tracks
+     */
+    getClipCount(): number;
+    /**
+     * Get clip count in a specific track
+     */
+    getClipCountInTrack(trackIndex: number): number;
+    /**
+     * Get the raw output configuration
+     */
+    getOutput(): Edit_2["output"];
+    /**
+     * Get output size (width/height)
+     * @throws Error if size is not defined
+     */
+    getSize(): Size;
+    /**
+     * Get output format (mp4, gif, etc.)
+     */
+    getFormat(): Edit_2["output"]["format"];
+    /**
+     * Get output FPS
+     */
+    getFps(): number | undefined;
+    /**
+     * Get output resolution preset
+     */
+    getResolution(): Edit_2["output"]["resolution"];
+    /**
+     * Get output aspect ratio
+     */
+    getAspectRatio(): Edit_2["output"]["aspectRatio"];
+    /**
+     * Get merge field definitions
+     */
+    getMergeFields(): Edit_2["merge"];
+    /**
+     * Add a new track at the specified index
+     * @returns The added track
+     */
+    addTrack(index: number, track?: Track): Track;
+    /**
+     * Remove a track at the specified index
+     * @returns The removed track, or null if index invalid
+     */
+    removeTrack(index: number): Track | null;
+    /**
+     * Add a clip to a track
+     * @returns The added clip
+     */
+    addClip(trackIndex: number, clip: Clip, clipIndex?: number): Clip;
+    /**
+     * Remove a clip from a track
+     * @returns The removed clip, or null if indices invalid
+     */
+    removeClip(trackIndex: number, clipIndex: number): Clip | null;
+    /**
+     * Update a clip's properties (partial update)
+     */
+    updateClip(trackIndex: number, clipIndex: number, updates: Partial<Clip>): void;
+    /**
+     * Replace a clip entirely
+     */
+    replaceClip(trackIndex: number, clipIndex: number, newClip: Clip): Clip | null;
+    /**
+     * Set timeline background color
+     */
+    setBackground(color: string): void;
+    /**
+     * Set soundtrack
+     */
+    setSoundtrack(soundtrack: Soundtrack | undefined): void;
+    /**
+     * Get timeline fonts
+     */
+    getFonts(): Array<{
+        src: string;
+    }>;
+    /**
+     * Add a font to the timeline (if not already present)
+     */
+    addFont(src: string): void;
+    /**
+     * Remove a font from the timeline
+     */
+    removeFont(src: string): void;
+    /**
+     * Set all timeline fonts (replaces existing)
+     */
+    setFonts(fonts: Array<{
+        src: string;
+    }>): void;
+    /**
+     * Set output size
+     */
+    setSize(size: Size): void;
+    /**
+     * Set output format
+     */
+    setFormat(format: Edit_2["output"]["format"]): void;
+    /**
+     * Set output FPS (must be a valid FPS value)
+     */
+    setFps(fps: Edit_2["output"]["fps"]): void;
+    /**
+     * Set output resolution preset
+     */
+    setResolution(resolution: Edit_2["output"]["resolution"]): void;
+    /**
+     * Clear output resolution preset
+     */
+    clearResolution(): void;
+    /**
+     * Set output aspect ratio
+     */
+    setAspectRatio(aspectRatio: Edit_2["output"]["aspectRatio"]): void;
+    /**
+     * Clear output aspect ratio
+     */
+    clearAspectRatio(): void;
+    /**
+     * Clear output size (for use when setting resolution/aspectRatio)
+     */
+    clearSize(): void;
+    /**
+     * Set merge field definitions
+     */
+    setMergeFields(mergeFields: Edit_2["merge"]): void;
+    /**
+     * Export the document as raw Edit JSON (preserves "auto", "end", placeholders)
+     * This is what gets sent to the backend API.
+     */
+    toJSON(): Edit_2;
+    /**
+     * Create an EditDocument from raw Edit JSON
+     */
+    static fromJSON(json: Edit_2): EditDocument;
+    /**
+     * Create a deep clone of this document
+     */
+    clone(): EditDocument;
+}
+
 export declare const EditEvent: {
     readonly PlaybackPlay: "playback:play";
     readonly PlaybackPause: "playback:pause";
@@ -1240,6 +1441,7 @@ export declare class MediaToolbar extends BaseToolbar {
     private fitLabel;
     private volumeSlider;
     private volumeValue;
+    private volumeDisplayInput;
     private volumeSection;
     private visualSection;
     private audioSection;
@@ -1264,6 +1466,18 @@ export declare class MediaToolbar extends BaseToolbar {
     private handleOpacityChange;
     private handleScaleChange;
     private handleVolumeChange;
+    /**
+     * Parse and commit the value from the volume text input.
+     */
+    private commitVolumeInputValue;
+    /**
+     * Revert the volume text input to match the current slider value.
+     */
+    private revertVolumeInputValue;
+    /**
+     * Parse user input, strip non-numeric chars, clamp to 0-100.
+     */
+    private parseVolumeInputValue;
     private applyTransitionUpdate;
     private applyEffect;
     private handleAudioFadeSelect;
@@ -1439,12 +1653,8 @@ declare interface PlaybackHealth {
  * Base class for all visual content players in the canvas.
  *
  * Player is responsible for rendering clip content (video, image, text, etc.)
- * and applying keyframe animations. It does NOT handle selection UI or
- * drag/resize/rotate interactions - those are handled by SelectionHandles
- * when registered via UIController.
+ * and applying keyframe animations.
  *
- * This separation allows Canvas to be used as a pure preview renderer
- * without any interactive overlays.
  */
 declare abstract class Player extends Entity {
     private static readonly DiscardedFrameCount;
@@ -1466,7 +1676,6 @@ declare abstract class Player extends Entity {
     protected contentContainer: pixi.Container;
     /**
      * Tracks which properties came from merge field templates.
-     * Key: property path (e.g., "asset.src"), Value: binding info
      */
     private mergeFieldBindings;
     constructor(edit: Edit, clipConfiguration: ResolvedClip, playerType: PlayerType);
@@ -1490,10 +1699,8 @@ declare abstract class Player extends Entity {
     setTimingIntent(intent: Partial<TimingIntent>): void;
     getResolvedTiming(): ResolvedTiming;
     setResolvedTiming(timing: ResolvedTiming): void;
-    convertToFixedTiming(): void;
     /**
      * Set a merge field binding for a property path.
-     * Called when a property is resolved from a merge field template.
      */
     setMergeFieldBinding(path: string, binding: MergeFieldBinding): void;
     /**
@@ -1514,20 +1721,15 @@ declare abstract class Player extends Entity {
     setInitialBindings(bindings: Map<string, MergeFieldBinding>): void;
     /**
      * Get the exportable clip configuration with merge field placeholders restored.
-     * For properties that haven't changed from their resolved value, the original
-     * placeholder (e.g., "{{ HERO_IMAGE }}") is restored for export.
      */
     getExportableClip(): Clip;
     /**
      * Get the playback time relative to clip start, in seconds.
-     * Used for keyframe animation calculations.
      */
     getPlaybackTime(): number;
     abstract getSize(): Size;
     /**
      * Returns the source content dimensions (before fit scaling).
-     * Override in subclasses that have different source vs output sizes.
-     * Default implementation returns getSize().
      */
     getContentSize(): Size;
     getOpacity(): number;
@@ -1578,6 +1780,20 @@ declare enum PlayerType {
 
 declare type ResolutionChangeCallback = (width: number, height: number) => void;
 
+/**
+ * Context required to resolve timing intent to concrete values.
+ *
+ * @see resolveTimingIntent - the pure function that uses this context
+ */
+declare interface ResolutionContext {
+    /** End time of previous clip on same track (for start: "auto") */
+    readonly previousClipEnd: Seconds;
+    /** Total duration of timeline excluding "end" clips (for length: "end") */
+    readonly timelineEnd: Seconds;
+    /** Intrinsic duration from asset metadata, null if not yet loaded (for length: "auto") */
+    readonly intrinsicDuration: Seconds | null;
+}
+
 declare type ResolvedClip = Omit<Clip, "start" | "length"> & {
     start: Seconds;
     length: Seconds;