@webpacked-timeline/core 1.0.0-beta.1

package/dist/index-Bw_nvNcG.d.cts

@@ -0,0 +1,1275 @@
+/**
+ * FRAME-BASED TIME REPRESENTATION
+ *
+ * This file defines the foundational time system for the entire timeline engine.
+ *
+ * WHY FRAMES INSTEAD OF MILLISECONDS?
+ * - Frames are discrete, integer values (no floating-point drift)
+ * - Frames are deterministic (same input always produces same output)
+ * - Frames match how video editors actually work (frame-accurate editing)
+ * - Frames prevent rounding errors that accumulate over time
+ *
+ * CRITICAL RULE:
+ * All time values in the timeline state MUST be stored as frames.
+ * Never store time as seconds or milliseconds in state.
+ *
+ * USAGE:
+ * ```typescript
+ * const fps = 30 as FrameRate;
+ * const frame = 150 as Frame;  // 5 seconds at 30fps
+ * ```
+ */
+/**
+ * Frame - A discrete point in time, measured in frames
+ *
+ * This is a "branded type" - it's just a number at runtime,
+ * but TypeScript treats it as a distinct type to prevent mixing
+ * frames with regular numbers accidentally.
+ *
+ * INVARIANT: Frame values must be non-negative integers
+ */
+type Frame = number & {
+    readonly __brand: 'Frame';
+};
+/**
+ * FrameRate - Frames per second (FPS)
+ *
+ * Common values: 24, 25, 30, 60
+ *
+ * INVARIANT: FrameRate must be a positive number
+ */
+type FrameRate = number & {
+    readonly __brand: 'FrameRate';
+};
+/**
+ * Create a Frame value from a number
+ *
+ * This function validates and rounds the input to ensure it's a valid frame number.
+ *
+ * @param value - The frame number (will be rounded to nearest integer)
+ * @returns A valid Frame value
+ * @throws Error if value is negative
+ */
+declare function frame(value: number): Frame;
+/**
+ * Create a FrameRate value from a number
+ *
+ * @param value - The frames per second
+ * @returns A valid FrameRate value
+ * @throws Error if value is not positive
+ */
+declare function frameRate(value: number): FrameRate;
+/**
+ * Check if a value is a valid frame number
+ *
+ * @param value - The value to check
+ * @returns true if the value is a non-negative integer
+ */
+declare function isValidFrame(value: number): boolean;
+/**
+ * Check if a value is a valid frame rate
+ *
+ * @param value - The value to check
+ * @returns true if the value is positive
+ */
+declare function isValidFrameRate(value: number): boolean;
+
+/**
+ * CLIP MODEL
+ *
+ * A Clip represents a time-bound reference to an Asset on a Track.
+ *
+ * WHAT IS A CLIP?
+ * - A piece of media placed at a specific time on the timeline
+ * - References an Asset (the source media)
+ * - Defines WHEN it appears (timeline bounds)
+ * - Defines WHAT portion of the asset to play (media bounds)
+ *
+ * KEY CONCEPTS:
+ *
+ * 1. TIMELINE BOUNDS:
+ *    - timelineStart: When the clip appears on the timeline
+ *    - timelineEnd: When the clip ends on the timeline
+ *    - Duration = timelineEnd - timelineStart
+ *
+ * 2. MEDIA BOUNDS:
+ *    - mediaIn: Start frame in the source asset
+ *    - mediaOut: End frame in the source asset
+ *    - Defines which portion of the asset to play
+ *
+ * EXAMPLE:
+ * ```typescript
+ * // A 10-second video asset
+ * const asset = { id: 'asset_1', duration: frame(300) };  // 300 frames at 30fps
+ *
+ * // A clip that shows 3 seconds of the video (frames 60-150)
+ * // starting at 5 seconds on the timeline
+ * const clip: Clip = {
+ *   id: 'clip_1',
+ *   assetId: 'asset_1',
+ *   trackId: 'track_1',
+ *   timelineStart: frame(150),  // 5 seconds * 30fps
+ *   timelineEnd: frame(240),    // 8 seconds * 30fps
+ *   mediaIn: frame(60),         // Start at 2 seconds into the asset
+ *   mediaOut: frame(150),       // End at 5 seconds into the asset
+ * };
+ * ```
+ *
+ * INVARIANTS (Phase 1 - No Speed Remapping):
+ * - timelineEnd > timelineStart
+ * - mediaOut > mediaIn
+ * - timelineEnd - timelineStart === mediaOut - mediaIn (same duration)
+ * - mediaOut <= asset.duration (can't exceed asset bounds)
+ * - All frame values must be non-negative
+ *
+ * FUTURE: When speed remapping is added, the duration constraint will change.
+ */
+
+/**
+ * Clip - A time-bound reference to an Asset
+ */
+interface Clip {
+    /** Unique identifier */
+    id: string;
+    /** Reference to the asset this clip uses */
+    assetId: string;
+    /** Reference to the track this clip belongs to */
+    trackId: string;
+    /** Start frame on the timeline */
+    timelineStart: Frame;
+    /** End frame on the timeline */
+    timelineEnd: Frame;
+    /** Start frame in the source asset */
+    mediaIn: Frame;
+    /** End frame in the source asset */
+    mediaOut: Frame;
+    /** Optional label for the clip */
+    label?: string;
+    /** Optional metadata for custom use cases */
+    metadata?: Record<string, unknown>;
+    /** Optional link group ID - clips in same group move/delete together */
+    linkGroupId?: string;
+    /** Optional group ID - for visual organization */
+    groupId?: string;
+}
+/**
+ * Create a new clip
+ *
+ * @param params - Clip parameters
+ * @returns A new Clip object
+ */
+declare function createClip(params: {
+    id: string;
+    assetId: string;
+    trackId: string;
+    timelineStart: Frame;
+    timelineEnd: Frame;
+    mediaIn: Frame;
+    mediaOut: Frame;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}): Clip;
+/**
+ * Get the timeline duration of a clip
+ *
+ * @param clip - The clip
+ * @returns Duration in frames
+ */
+declare function getClipDuration(clip: Clip): Frame;
+/**
+ * Get the media duration of a clip
+ *
+ * @param clip - The clip
+ * @returns Duration in frames
+ */
+declare function getClipMediaDuration(clip: Clip): Frame;
+/**
+ * Check if a clip contains a specific frame on the timeline
+ *
+ * @param clip - The clip
+ * @param frame - The frame to check
+ * @returns true if the frame is within the clip's timeline bounds
+ */
+declare function clipContainsFrame(clip: Clip, frame: Frame): boolean;
+/**
+ * Check if two clips overlap on the timeline
+ *
+ * @param clip1 - First clip
+ * @param clip2 - Second clip
+ * @returns true if the clips overlap
+ */
+declare function clipsOverlap(clip1: Clip, clip2: Clip): boolean;
+
+/**
+ * TRACK MODEL
+ *
+ * A Track is a horizontal container for Clips.
+ *
+ * WHAT IS A TRACK?
+ * - A layer that holds clips (like a layer in Photoshop)
+ * - Provides organization and isolation for clips
+ * - Has a type (video or audio) that clips must match
+ *
+ * WHY TRACKS?
+ * - Organize clips into layers
+ * - Enable stacking and compositing (track order matters)
+ * - Provide track-level controls (mute, lock)
+ * - Isolate editing operations
+ *
+ * TRACK ORDER:
+ * Tracks are rendered bottom-to-top:
+ * - tracks[0] = bottom layer (rendered first)
+ * - tracks[n] = top layer (rendered last, appears on top)
+ *
+ * EXAMPLE:
+ * ```typescript
+ * const track: Track = {
+ *   id: 'track_1',
+ *   name: 'Video Track 1',
+ *   type: 'video',
+ *   clips: [],
+ *   locked: false,
+ *   muted: false,
+ * };
+ * ```
+ *
+ * INVARIANTS:
+ * - Clips on a track must not overlap
+ * - All clips must match the track type
+ * - Clips array should be sorted by timelineStart (for performance)
+ */
+
+/**
+ * TrackType - The kind of content this track holds
+ */
+type TrackType = 'video' | 'audio';
+/**
+ * Track - A container for clips
+ */
+interface Track {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Type of content this track holds */
+    type: TrackType;
+    /** Clips on this track (should be sorted by timelineStart) */
+    clips: Clip[];
+    /** Whether the track is locked (prevents editing) */
+    locked: boolean;
+    /** Whether the track is muted (affects playback) */
+    muted: boolean;
+    /** Whether the track is soloed (mutes all other tracks) */
+    solo: boolean;
+    /** Track height in pixels (for UI rendering) */
+    height: number;
+    /** Optional metadata for custom use cases */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a new track
+ *
+ * @param params - Track parameters
+ * @returns A new Track object
+ */
+declare function createTrack(params: {
+    id: string;
+    name: string;
+    type: TrackType;
+    clips?: Clip[];
+    locked?: boolean;
+    muted?: boolean;
+    solo?: boolean;
+    height?: number;
+    metadata?: Record<string, unknown>;
+}): Track;
+/**
+ * Sort clips on a track by timeline start frame
+ *
+ * This is useful for maintaining clip order and improving
+ * query performance.
+ *
+ * @param track - The track to sort
+ * @returns A new track with sorted clips
+ */
+declare function sortTrackClips(track: Track): Track;
+
+/**
+ * TIMELINE MODEL
+ *
+ * The Timeline is the root container for the entire editing project.
+ *
+ * WHAT IS A TIMELINE?
+ * - The top-level data structure for a project
+ * - Contains all tracks (which contain all clips)
+ * - Defines the frame rate (FPS) for the entire project
+ * - Defines the total duration of the project
+ *
+ * WHY A TIMELINE?
+ * - Single source of truth for all timeline data
+ * - Defines the temporal bounds of the project
+ * - Provides a consistent frame rate for all time calculations
+ *
+ * EXAMPLE:
+ * ```typescript
+ * const timeline: Timeline = {
+ *   id: 'timeline_1',
+ *   name: 'My Project',
+ *   fps: frameRate(30),
+ *   duration: frame(9000),  // 5 minutes at 30fps
+ *   tracks: [],
+ * };
+ * ```
+ *
+ * INVARIANTS:
+ * - FPS is immutable after timeline creation
+ * - Duration must be positive
+ * - All tracks must have unique IDs
+ */
+
+/**
+ * Timeline - The root container for a timeline project
+ */
+interface Timeline {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Frames per second (immutable after creation) */
+    fps: FrameRate;
+    /** Total duration of the timeline in frames */
+    duration: Frame;
+    /** Tracks in the timeline (ordered bottom-to-top) */
+    tracks: Track[];
+    /** Optional metadata for custom use cases */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a new timeline
+ *
+ * @param params - Timeline parameters
+ * @returns A new Timeline object
+ */
+declare function createTimeline(params: {
+    id: string;
+    name: string;
+    fps: FrameRate;
+    duration: Frame;
+    tracks?: Track[];
+    metadata?: Record<string, unknown>;
+}): Timeline;
+
+/**
+ * ASSET MODEL
+ *
+ * An Asset represents immutable metadata about a media file.
+ *
+ * WHAT IS AN ASSET?
+ * - A reference to source media (video, audio, image)
+ * - Contains metadata like duration and type
+ * - Immutable once registered (duration never changes)
+ *
+ * WHY SEPARATE ASSETS FROM CLIPS?
+ * - Multiple clips can reference the same asset
+ * - Asset duration is the source of truth
+ * - Clips can trim/slice the asset without modifying it
+ *
+ * EXAMPLE:
+ * ```typescript
+ * const asset: Asset = {
+ *   id: 'asset_1',
+ *   type: 'video',
+ *   duration: frame(3600),  // 2 minutes at 30fps
+ *   sourceUrl: 'https://example.com/video.mp4',
+ * };
+ * ```
+ *
+ * INVARIANTS:
+ * - Asset ID must be unique
+ * - Duration must be positive
+ * - Duration is immutable after registration
+ */
+
+/**
+ * AssetType - The kind of media this asset represents
+ */
+type AssetType = 'video' | 'audio' | 'image';
+/**
+ * Asset - Immutable metadata about a media file
+ */
+interface Asset {
+    /** Unique identifier */
+    id: string;
+    /** Type of media */
+    type: AssetType;
+    /** Total duration of the asset in frames */
+    duration: Frame;
+    /** Source URL or file path */
+    sourceUrl: string;
+    /** Optional metadata for custom use cases */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Create a new asset
+ *
+ * @param params - Asset parameters
+ * @returns A new Asset object
+ */
+declare function createAsset(params: {
+    id: string;
+    type: AssetType;
+    duration: Frame;
+    sourceUrl: string;
+    metadata?: Record<string, unknown>;
+}): Asset;
+
+/**
+ * LINKING TYPES
+ *
+ * Link groups synchronize edits across multiple clips.
+ * When one clip in a link group is moved/deleted, all linked clips are affected.
+ */
+/**
+ * Link group - relates clips for synchronized editing
+ */
+interface LinkGroup {
+    id: string;
+    clipIds: string[];
+    createdAt?: number;
+}
+
+/**
+ * GROUPING TYPES
+ *
+ * Groups organize clips visually without affecting edit behavior.
+ * Unlike link groups, groups are for organization only.
+ */
+/**
+ * Group - organizes clips visually
+ */
+interface Group {
+    id: string;
+    name: string;
+    clipIds: string[];
+    parentGroupId?: string;
+    color?: string;
+    collapsed?: boolean;
+}
+
+/**
+ * MARKER TYPES
+ *
+ * Pure metadata for timeline navigation and organization.
+ * Markers do not affect clip timing or validation.
+ */
+
+/**
+ * Timeline marker - marks a specific frame on the timeline
+ */
+interface TimelineMarker {
+    id: string;
+    type: 'timeline';
+    frame: Frame;
+    label: string;
+    color?: string;
+}
+/**
+ * Clip marker - marks a frame relative to clip start
+ */
+interface ClipMarker {
+    id: string;
+    type: 'clip';
+    clipId: string;
+    frame: Frame;
+    label: string;
+    color?: string;
+}
+/**
+ * Region marker - marks a frame range
+ */
+interface RegionMarker {
+    id: string;
+    type: 'region';
+    startFrame: Frame;
+    endFrame: Frame;
+    label: string;
+    color?: string;
+}
+/**
+ * Work area - defines the active editing region
+ */
+interface WorkArea {
+    startFrame: Frame;
+    endFrame: Frame;
+}
+/**
+ * Union type for all marker types
+ */
+type Marker = TimelineMarker | ClipMarker | RegionMarker;
+
+/**
+ * TIMELINE STATE
+ *
+ * This is the complete state shape for the timeline engine.
+ *
+ * WHAT IS TIMELINE STATE?
+ * - The root state object that contains everything
+ * - Timeline (tracks and clips)
+ * - Assets (media metadata)
+ *
+ * WHY SEPARATE STATE?
+ * - Clear separation between timeline structure and asset registry
+ * - Assets can be shared across multiple clips
+ * - State is the single source of truth
+ *
+ * EXAMPLE:
+ * ```typescript
+ * const state: TimelineState = {
+ *   timeline: {
+ *     id: 'timeline_1',
+ *     name: 'My Project',
+ *     fps: frameRate(30),
+ *     duration: frame(9000),
+ *     tracks: [],
+ *   },
+ *   assets: new Map([
+ *     ['asset_1', { id: 'asset_1', type: 'video', duration: frame(3600), sourceUrl: '...' }],
+ *   ]),
+ * };
+ * ```
+ *
+ * IMMUTABILITY:
+ * All operations on TimelineState must return a NEW state object.
+ * Never mutate the existing state.
+ */
+
+/**
+ * TimelineState - The complete state for the timeline engine
+ *
+ * Phase 2 additions:
+ * - linkGroups: Synchronized editing groups
+ * - groups: Visual organization groups
+ * - markers: Timeline/clip/region markers
+ * - workArea: Active editing region
+ */
+interface TimelineState {
+    /** The timeline (tracks and clips) */
+    timeline: Timeline;
+    /** Asset registry (media metadata) */
+    assets: Map<string, Asset>;
+    /** Link groups for synchronized editing */
+    linkGroups: Map<string, LinkGroup>;
+    /** Groups for visual organization */
+    groups: Map<string, Group>;
+    /** Markers for navigation and annotation */
+    markers: {
+        timeline: TimelineMarker[];
+        clips: ClipMarker[];
+        regions: RegionMarker[];
+    };
+    /** Optional work area definition */
+    workArea?: WorkArea;
+}
+/**
+ * Create a new timeline state
+ *
+ * @param params - State parameters
+ * @returns A new TimelineState object
+ */
+declare function createTimelineState(params: {
+    timeline: Timeline;
+    assets?: Map<string, Asset>;
+    linkGroups?: Map<string, LinkGroup>;
+    groups?: Map<string, Group>;
+    markers?: {
+        timeline: TimelineMarker[];
+        clips: ClipMarker[];
+        regions: RegionMarker[];
+    };
+    workArea?: WorkArea;
+}): TimelineState;
+
+/**
+ * HISTORY ENGINE
+ *
+ * Snapshot-based undo/redo system for timeline state.
+ *
+ * WHAT IS THE HISTORY ENGINE?
+ * - Stores immutable snapshots of timeline state
+ * - Provides undo/redo functionality
+ * - Prevents state corruption
+ *
+ * HOW IT WORKS:
+ * - past: Array of previous states
+ * - present: Current state
+ * - future: Array of states that can be redone
+ *
+ * WHY SNAPSHOTS?
+ * - Simple and reliable (no complex diffing)
+ * - Guaranteed to restore exact state
+ * - No risk of partial corruption
+ * - Easy to implement and test
+ *
+ * USAGE:
+ * ```typescript
+ * let history = createHistory(initialState);
+ * history = pushHistory(history, newState);
+ * history = undo(history);
+ * history = redo(history);
+ * ```
+ *
+ * ALL FUNCTIONS ARE PURE:
+ * - Take history as input
+ * - Return new history as output
+ * - Never mutate input
+ */
+
+/**
+ * HistoryState - The history container
+ *
+ * Contains:
+ * - past: Array of previous states (oldest first)
+ * - present: Current state
+ * - future: Array of states that can be redone (newest first)
+ * - limit: Maximum number of past states to keep
+ */
+interface HistoryState {
+    past: TimelineState[];
+    present: TimelineState;
+    future: TimelineState[];
+    limit: number;
+}
+
+/**
+ * VALIDATION SYSTEM TYPES
+ *
+ * This file defines the structure for validation results throughout the engine.
+ *
+ * WHY STRUCTURED VALIDATION?
+ * - Operations can fail gracefully (no exceptions thrown)
+ * - Errors are descriptive and actionable
+ * - Multiple errors can be collected and reported together
+ * - Validation logic is separated from business logic
+ *
+ * USAGE:
+ * ```typescript
+ * const result = validateClip(state, clip);
+ * if (!result.valid) {
+ *   console.error('Validation failed:', result.errors);
+ *   return;
+ * }
+ * ```
+ */
+/**
+ * ValidationError - A single validation error
+ *
+ * Contains:
+ * - code: Machine-readable error code (e.g., "CLIP_OVERLAP")
+ * - message: Human-readable error message
+ * - context: Optional additional data about the error
+ */
+interface ValidationError {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Optional context data for debugging */
+    context?: Record<string, unknown>;
+}
+/**
+ * ValidationResult - The result of a validation operation
+ *
+ * Contains:
+ * - valid: Whether the validation passed
+ * - errors: Array of validation errors (empty if valid)
+ */
+interface ValidationResult {
+    /** Whether the validation passed */
+    valid: boolean;
+    /** Array of validation errors (empty if valid) */
+    errors: ValidationError[];
+}
+/**
+ * Create a successful validation result
+ *
+ * @returns A ValidationResult indicating success
+ */
+declare function validResult(): ValidationResult;
+/**
+ * Create a failed validation result with a single error
+ *
+ * @param code - Error code
+ * @param message - Error message
+ * @param context - Optional context data
+ * @returns A ValidationResult indicating failure
+ */
+declare function invalidResult(code: string, message: string, context?: Record<string, unknown>): ValidationResult;
+/**
+ * Create a failed validation result with multiple errors
+ *
+ * @param errors - Array of validation errors
+ * @returns A ValidationResult indicating failure
+ */
+declare function invalidResults(errors: ValidationError[]): ValidationResult;
+/**
+ * Combine multiple validation results
+ *
+ * If any result is invalid, the combined result is invalid.
+ * All errors are collected together.
+ *
+ * @param results - Array of validation results to combine
+ * @returns A combined ValidationResult
+ */
+declare function combineResults(...results: ValidationResult[]): ValidationResult;
+
+/**
+ * DISPATCH ORCHESTRATION
+ *
+ * Coordinates operation execution, validation, and history management.
+ *
+ * WHAT IS THE DISPATCHER?
+ * - Executes operations on state
+ * - Validates the resulting state
+ * - Commits valid states to history
+ * - Rejects invalid states with errors
+ *
+ * WHY A DISPATCHER?
+ * - Enforces validation before mutation
+ * - Prevents invalid states from entering history
+ * - Provides consistent error handling
+ * - Separates concerns (operations vs validation vs history)
+ *
+ * CRITICAL FLOW:
+ * 1. Execute operation (pure function)
+ * 2. Validate resulting state
+ * 3. If valid: push to history, return success
+ * 4. If invalid: return errors, state unchanged
+ *
+ * USAGE:
+ * ```typescript
+ * const result = dispatch(history, (state) => addClip(state, trackId, clip));
+ * if (result.success) {
+ *   history = result.history;
+ * } else {
+ *   console.error('Operation failed:', result.errors);
+ * }
+ * ```
+ */
+
+/**
+ * DispatchResult - The result of a dispatch operation
+ *
+ * Contains:
+ * - success: Whether the operation succeeded
+ * - history: Updated history (if success) or unchanged (if failure)
+ * - errors: Validation errors (if failure)
+ */
+interface DispatchResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Updated history state */
+    history: HistoryState;
+    /** Validation errors (if operation failed) */
+    errors?: ValidationError[];
+}
+
+/**
+ * TIMELINE ENGINE
+ *
+ * The main public API for the timeline editing kernel.
+ *
+ * WHAT IS THE TIMELINE ENGINE?
+ * - A thin wrapper around the history and dispatch systems
+ * - Provides a convenient, object-oriented API
+ * - Manages internal state
+ * - Coordinates operations, validation, and history
+ *
+ * WHY A CLASS?
+ * - Encapsulates state management
+ * - Provides a clean API for users
+ * - Hides complexity of history and dispatch
+ * - Familiar OOP interface for most developers
+ *
+ * USAGE:
+ * ```typescript
+ * const engine = new TimelineEngine(initialState);
+ *
+ * // Add a clip
+ * const result = engine.addClip(trackId, clip);
+ * if (!result.success) {
+ *   console.error('Failed to add clip:', result.errors);
+ * }
+ *
+ * // Undo/redo
+ * engine.undo();
+ * engine.redo();
+ *
+ * // Query state
+ * const clip = engine.findClipById('clip_1');
+ * const state = engine.getState();
+ * ```
+ *
+ * DESIGN PHILOSOPHY:
+ * - Business logic lives in pure modules (operations, validation, etc.)
+ * - Engine is just a thin orchestration layer
+ * - Easy to test (can test pure functions independently)
+ */
+
+/**
+ * TimelineEngine - The main timeline editing engine
+ *
+ * Provides a high-level API for timeline editing with built-in
+ * undo/redo, validation, and state management.
+ */
+declare class TimelineEngine {
+    private history;
+    private listeners;
+    /**
+     * Create a new timeline engine
+     *
+     * @param initialState - Initial timeline state
+     * @param historyLimit - Maximum number of undo steps (default: 50)
+     */
+    constructor(initialState: TimelineState, historyLimit?: number);
+    /**
+     * Subscribe to state changes
+     *
+     * The listener will be called whenever the timeline state changes,
+     * with the new state passed as an argument.
+     * This is used by framework adapters (e.g., React) to trigger re-renders.
+     *
+     * @param listener - Function to call on state changes, receives new state
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = engine.subscribe((state) => {
+     *   console.log('State changed:', state);
+     * });
+     *
+     * // Later...
+     * unsubscribe();
+     * ```
+     */
+    subscribe(listener: (state: TimelineState) => void): () => void;
+    /**
+     * Notify all subscribers of a state change
+     *
+     * This is called internally after any operation that modifies state.
+     * Framework adapters use this to trigger re-renders.
+     */
+    private notify;
+    /**
+     * Get the current timeline state
+     *
+     * @returns Current timeline state
+     */
+    getState(): TimelineState;
+    /**
+     * Register an asset
+     *
+     * @param asset - Asset to register
+     * @returns Dispatch result
+     */
+    registerAsset(asset: Asset): DispatchResult;
+    /**
+     * Get an asset by ID
+     *
+     * @param assetId - Asset ID
+     * @returns The asset, or undefined if not found
+     */
+    getAsset(assetId: string): Asset | undefined;
+    /**
+     * Add a clip to a track
+     *
+     * @param trackId - ID of the track to add to
+     * @param clip - Clip to add
+     * @returns Dispatch result
+     */
+    addClip(trackId: string, clip: Clip): DispatchResult;
+    /**
+     * Remove a clip
+     *
+     * @param clipId - ID of the clip to remove
+     * @returns Dispatch result
+     */
+    removeClip(clipId: string): DispatchResult;
+    /**
+     * Move a clip to a new timeline position
+     *
+     * @param clipId - ID of the clip to move
+     * @param newStart - New timeline start frame
+     * @returns Dispatch result
+     */
+    moveClip(clipId: string, newStart: Frame): DispatchResult;
+    /**
+     * Resize a clip
+     *
+     * @param clipId - ID of the clip to resize
+     * @param newStart - New timeline start frame
+     * @param newEnd - New timeline end frame
+     * @returns Dispatch result
+     */
+    resizeClip(clipId: string, newStart: Frame, newEnd: Frame): DispatchResult;
+    /**
+     * Trim a clip (change media bounds)
+     *
+     * @param clipId - ID of the clip to trim
+     * @param newMediaIn - New media in frame
+     * @param newMediaOut - New media out frame
+     * @returns Dispatch result
+     */
+    trimClip(clipId: string, newMediaIn: Frame, newMediaOut: Frame): DispatchResult;
+    /**
+     * Move a clip to a different track
+     *
+     * @param clipId - ID of the clip to move
+     * @param targetTrackId - ID of the target track
+     * @returns Dispatch result
+     */
+    moveClipToTrack(clipId: string, targetTrackId: string): DispatchResult;
+    /**
+     * Add a track
+     *
+     * @param track - Track to add
+     * @returns Dispatch result
+     */
+    addTrack(track: Track): DispatchResult;
+    /**
+     * Remove a track
+     *
+     * @param trackId - ID of the track to remove
+     * @returns Dispatch result
+     */
+    removeTrack(trackId: string): DispatchResult;
+    /**
+     * Move a track to a new position
+     *
+     * @param trackId - ID of the track to move
+     * @param newIndex - New index position
+     * @returns Dispatch result
+     */
+    moveTrack(trackId: string, newIndex: number): DispatchResult;
+    /**
+     * Toggle track mute
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackMute(trackId: string): DispatchResult;
+    /**
+     * Toggle track lock
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackLock(trackId: string): DispatchResult;
+    /**
+     * Toggle track solo
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackSolo(trackId: string): DispatchResult;
+    /**
+     * Set track height
+     *
+     * @param trackId - ID of the track
+     * @param height - New height in pixels
+     * @returns Dispatch result
+     */
+    setTrackHeight(trackId: string, height: number): DispatchResult;
+    /**
+     * Set timeline duration
+     *
+     * @param duration - New duration in frames
+     * @returns Dispatch result
+     */
+    setTimelineDuration(duration: Frame): DispatchResult;
+    /**
+     * Set timeline name
+     *
+     * @param name - New timeline name
+     * @returns Dispatch result
+     */
+    setTimelineName(name: string): DispatchResult;
+    /**
+     * Undo the last action
+     *
+     * @returns true if undo was performed
+     */
+    undo(): boolean;
+    /**
+     * Redo the last undone action
+     *
+     * @returns true if redo was performed
+     */
+    redo(): boolean;
+    /**
+     * Check if undo is available
+     *
+     * @returns true if undo is available
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     *
+     * @returns true if redo is available
+     */
+    canRedo(): boolean;
+    /**
+     * Find a clip by ID
+     *
+     * @param clipId - Clip ID
+     * @returns The clip, or undefined if not found
+     */
+    findClipById(clipId: string): Clip | undefined;
+    /**
+     * Find a track by ID
+     *
+     * @param trackId - Track ID
+     * @returns The track, or undefined if not found
+     */
+    findTrackById(trackId: string): Track | undefined;
+    /**
+     * Get all clips on a track
+     *
+     * @param trackId - Track ID
+     * @returns Array of clips on the track
+     */
+    getClipsOnTrack(trackId: string): Clip[];
+    /**
+     * Get all clips at a specific frame
+     *
+     * @param frame - Frame to check
+     * @returns Array of clips at that frame
+     */
+    getClipsAtFrame(frame: Frame): Clip[];
+    /**
+     * Get all clips in a frame range
+     *
+     * @param start - Start frame
+     * @param end - End frame
+     * @returns Array of clips in the range
+     */
+    getClipsInRange(start: Frame, end: Frame): Clip[];
+    /**
+     * Get all clips in the timeline
+     *
+     * @returns Array of all clips
+     */
+    getAllClips(): Clip[];
+    /**
+     * Get all tracks in the timeline
+     *
+     * @returns Array of all tracks
+     */
+    getAllTracks(): Track[];
+    /**
+     * Ripple delete - delete clip and shift subsequent clips left
+     *
+     * @param clipId - ID of the clip to delete
+     * @returns Dispatch result
+     */
+    rippleDelete(clipId: string): DispatchResult;
+    /**
+     * Ripple trim - trim clip end and shift subsequent clips
+     *
+     * @param clipId - ID of the clip to trim
+     * @param newEnd - New end frame for the clip
+     * @returns Dispatch result
+     */
+    rippleTrim(clipId: string, newEnd: Frame): DispatchResult;
+    /**
+     * Insert edit - insert clip and shift subsequent clips right
+     *
+     * @param trackId - ID of the track to insert into
+     * @param clip - Clip to insert
+     * @param atFrame - Frame to insert at
+     * @returns Dispatch result
+     */
+    insertEdit(trackId: string, clip: Clip, atFrame: Frame): DispatchResult;
+    /**
+     * Ripple move - move clip and shift surrounding clips to accommodate
+     *
+     * This moves a clip to a new position while maintaining timeline continuity:
+     * - Closes the gap at the source position
+     * - Makes space at the destination position
+     * - All operations are atomic (single undo entry)
+     *
+     * @param clipId - ID of the clip to move
+     * @param newStart - New start frame for the clip
+     * @returns Dispatch result
+     */
+    rippleMove(clipId: string, newStart: Frame): DispatchResult;
+    /**
+     * Insert move - move clip and shift destination clips right
+     *
+     * This moves a clip to a new position without closing the gap at source:
+     * - Leaves gap at the source position
+     * - Pushes all clips at destination right to make space
+     * - All operations are atomic (single undo entry)
+     *
+     * @param clipId - ID of the clip to move
+     * @param newStart - New start frame for the clip
+     * @returns Dispatch result
+     */
+    insertMove(clipId: string, newStart: Frame): DispatchResult;
+    /**
+     * Add a timeline marker
+     *
+     * @param marker - Timeline marker to add
+     * @returns Dispatch result
+     */
+    addTimelineMarker(marker: TimelineMarker): DispatchResult;
+    /**
+     * Add a clip marker
+     *
+     * @param marker - Clip marker to add
+     * @returns Dispatch result
+     */
+    addClipMarker(marker: ClipMarker): DispatchResult;
+    /**
+     * Add a region marker
+     *
+     * @param marker - Region marker to add
+     * @returns Dispatch result
+     */
+    addRegionMarker(marker: RegionMarker): DispatchResult;
+    /**
+     * Remove a marker by ID
+     *
+     * @param markerId - ID of the marker to remove
+     * @returns Dispatch result
+     */
+    removeMarker(markerId: string): DispatchResult;
+    /**
+     * Update a timeline marker
+     *
+     * @param markerId - ID of the marker to update
+     * @param updates - Partial marker updates
+     * @returns Dispatch result
+     */
+    updateTimelineMarker(markerId: string, updates: Partial<Omit<TimelineMarker, 'id' | 'type'>>): DispatchResult;
+    /**
+     * Update a region marker
+     *
+     * @param markerId - ID of the marker to update
+     * @param updates - Partial marker updates
+     * @returns Dispatch result
+     */
+    updateRegionMarker(markerId: string, updates: Partial<Omit<RegionMarker, 'id' | 'type'>>): DispatchResult;
+    /**
+     * Set work area
+     *
+     * @param start - Start frame
+     * @param end - End frame
+     * @returns Dispatch result
+     */
+    setWorkArea(start: Frame, end: Frame): DispatchResult;
+    /**
+     * Clear work area
+     *
+     * @returns Dispatch result
+     */
+    clearWorkArea(): DispatchResult;
+}
+
+/**
+ * FRAME UTILITIES
+ *
+ * Pure functions for working with frame-based time values.
+ *
+ * These utilities handle:
+ * - Converting between frames and seconds
+ * - Formatting frames as timecode (HH:MM:SS:FF)
+ * - Frame arithmetic (clamping, rounding)
+ *
+ * CRITICAL RULES:
+ * - All conversions must quantize to whole frames
+ * - No floating-point frame values allowed
+ * - Always round/floor/ceil explicitly
+ *
+ * USAGE:
+ * ```typescript
+ * const fps = frameRate(30);
+ * const frames = secondsToFrames(5.5, fps);  // 165 frames
+ * const seconds = framesToSeconds(frames, fps);  // 5.5 seconds
+ * const timecode = framesToTimecode(frames, fps);  // "00:00:05:15"
+ * ```
+ */
+
+/**
+ * Convert frames to seconds
+ *
+ * @param frames - Frame number
+ * @param fps - Frames per second
+ * @returns Time in seconds (may be fractional)
+ */
+declare function framesToSeconds(frames: Frame, fps: FrameRate): number;
+/**
+ * Convert seconds to frames
+ *
+ * IMPORTANT: This rounds to the nearest frame.
+ * If you need different rounding behavior, use Math.floor or Math.ceil explicitly.
+ *
+ * @param seconds - Time in seconds
+ * @param fps - Frames per second
+ * @returns Frame number (rounded to nearest frame)
+ */
+declare function secondsToFrames(seconds: number, fps: FrameRate): Frame;
+/**
+ * Convert frames to timecode format (HH:MM:SS:FF)
+ *
+ * Example: 3825 frames at 30fps = "00:02:07:15"
+ *
+ * @param frames - Frame number
+ * @param fps - Frames per second
+ * @returns Timecode string
+ */
+declare function framesToTimecode(frames: Frame, fps: FrameRate): string;
+/**
+ * Convert frames to simple MM:SS format
+ *
+ * Example: 3825 frames at 30fps = "02:07"
+ *
+ * @param frames - Frame number
+ * @param fps - Frames per second
+ * @returns Time string in MM:SS format
+ */
+declare function framesToMinutesSeconds(frames: Frame, fps: FrameRate): string;
+/**
+ * Clamp a frame value between min and max
+ *
+ * @param value - Frame to clamp
+ * @param min - Minimum frame (inclusive)
+ * @param max - Maximum frame (inclusive)
+ * @returns Clamped frame value
+ */
+declare function clampFrame(value: Frame, min: Frame, max: Frame): Frame;
+/**
+ * Add two frame values
+ *
+ * @param a - First frame
+ * @param b - Second frame
+ * @returns Sum of frames
+ */
+declare function addFrames(a: Frame, b: Frame): Frame;
+/**
+ * Subtract two frame values
+ *
+ * @param a - First frame
+ * @param b - Second frame (subtracted from a)
+ * @returns Difference of frames (clamped to 0 if negative)
+ */
+declare function subtractFrames(a: Frame, b: Frame): Frame;
+/**
+ * Calculate duration between two frames
+ *
+ * @param start - Start frame
+ * @param end - End frame
+ * @returns Duration in frames (end - start)
+ */
+declare function frameDuration(start: Frame, end: Frame): Frame;
+
+export { type Asset as A, getClipMediaDuration as B, type Clip as C, type DispatchResult as D, invalidResult as E, type Frame as F, type Group as G, invalidResults as H, isValidFrame as I, isValidFrameRate as J, secondsToFrames as K, type LinkGroup as L, type Marker as M, sortTrackClips as N, subtractFrames as O, validResult as P, type RegionMarker as R, type TimelineState as T, type ValidationResult as V, type WorkArea as W, type Track as a, type ClipMarker as b, type TimelineMarker as c, type AssetType as d, type FrameRate as e, type Timeline as f, TimelineEngine as g, type TrackType as h, type ValidationError as i, addFrames as j, clampFrame as k, clipContainsFrame as l, clipsOverlap as m, combineResults as n, createAsset as o, createClip as p, createTimeline as q, createTimelineState as r, createTrack as s, frame as t, frameDuration as u, frameRate as v, framesToMinutesSeconds as w, framesToSeconds as x, framesToTimecode as y, getClipDuration as z };