@webpacked-timeline/core 1.0.0-beta.1

package/dist/internal.d.cts

@@ -0,0 +1,704 @@
+import { T as TimelineState, C as Clip, a as Track, b as TimelineFrame, A as Asset } from './index-wiGRwVyY.cjs';
+export { c as AAFExportOptions, d as AnimatableProperty, e as AssetId, f as AssetRegistry, g as AssetRemapCallback, h as AssetStatus, i as AudioChunkRequest, j as AudioChunkResult, k as AudioDecoder, l as AudioProperties, B as Bin, m as BinId, n as BinItem, o as CURRENT_SCHEMA_VERSION, p as ChannelRouting, q as ClipEntry, r as ClipId, s as ClipTransform, t as Clock, u as CompositeLayer, v as CompositeRequest, w as CompositeResult, x as Compositor, y as CompressibleOpType, z as CompressionPolicy, D as DEFAULT_AUDIO_PROPERTIES, E as DEFAULT_CLIP_TRANSFORM, F as DEFAULT_COMPRESSION_POLICY, G as DEFAULT_KEY_BINDINGS, H as DispatchResult, I as EDLExportOptions, J as EMPTY_STATE_CHANGE, K as EasingCurve, L as Effect, M as EffectId, N as EffectParam, O as EffectType, P as FCPXMLExportOptions, Q as FrameRate, R as FrameRates, S as HOLD_EASING, U as HandTool, V as HistoryEntry, W as HistoryStack, X as HistoryState, Y as ITool, Z as Interval, _ as IntervalTree, $ as InvariantViolation, a0 as KeyBinding, a1 as KeyboardHandler, a2 as KeyboardHandlerOptions, a3 as Keyframe, a4 as KeyframeId, a5 as KeyframeTool, a6 as LINEAR_EASING, a7 as LinkGroup, a8 as LinkGroupId, a9 as LoopRegion, aa as MarkerId, ab as Modifiers, ac as NO_COMPRESSION, ad as NoOpTool, ae as OTIODocument, af as OTIOImportOptions, ag as OfflineAsset, ah as OperationPrimitive, ai as PipelineConfig, aj as PlaybackEngine, ak as PlaybackQuality, al as PlaybackRate, am as PlayheadController, an as PlayheadEvent, ao as PlayheadEventType, ap as PlayheadListener, aq as PlayheadState, ar as PlayheadUnsubscribe, as as Project, at as ProjectId, au as ProvisionalManager, av as ProvisionalState, aw as RationalTime, ax as RazorTool, ay as RejectionReason, az as RenderStage, aA as RippleDeleteTool, aB as RippleInsertTool, aC as RippleTrimTool, aD as RollTrimTool, aE as RubberBandRegion, aF as SRTParseOptions, aG as SelectionTool, aH as SequenceSettings, aI as SerializationError, aJ as SlideTool, aK as SlipTool, aL as SnapIndex, aM as SnapIndexManager, aN as SnapPoint, aO as SnapPointType, aP as StateChange, aQ as ThumbnailCache, aR as ThumbnailPriority, aS as ThumbnailProvider, aT as ThumbnailQueue, aU as ThumbnailQueueEntry, aV as ThumbnailRequest, aW as ThumbnailResult, aX as ThumbnailWorkerMessage, aY as ThumbnailWorkerResponse, aZ as TimeRange, a_ as Timecode, a$ as Timeline, b0 as TimelineEngine, b1 as TimelineKeyAction, b2 as TimelineKeyEvent, b3 as TimelinePointerEvent, b4 as ToolContext, b5 as ToolId, b6 as ToolRegistry, b7 as TrackGroup, b8 as TrackGroupId, b9 as TrackId, ba as TrackIndex, bb as TrackType, bc as Transaction, bd as TransactionCompressor, be as Transition, bf as TransitionAlignment, bg as TransitionId, bh as TransitionParam, bi as TransitionTool, bj as TransitionType, bk as VTTParseOptions, bl as VideoDecoder, bm as VideoFrameRequest, bn as VideoFrameResult, bo as ViolationType, bp as VirtualClipEntry, bq as VirtualWindow, br as WaveformPeak, bs as WaveformRequest, bt as WaveformResult, bu as WaveformWorkerMessage, bv as WaveformWorkerResponse, bw as ZoomTool, bx as ZoomToolOptions, by as activateTool, by as activateToolInRegistry, bz as addBin, bA as addFrames, bB as addItemToBin, bC as addTimeline, bD as browserClock, bE as buildSnapIndex, bF as canRedo, bG as canUndo, bH as checkInvariants, bI as clampFrame, bJ as clearProvisional, bK as clipContainsFrame, bL as clipsOverlap, bM as createAnimatableProperty, bN as createAsset, bO as createBin, bP as createClip, bQ as createEffect, bR as createHistory, bS as createLinkGroup, bT as createProject, bU as createProvisionalManager, bV as createRegistry, bW as createTestClock, bX as createTimeline, bY as createTimelineState, bZ as createTrack, b_ as createTrackGroup, b$ as createTransition, c0 as createZoomTool, c1 as defaultCaptionStyle, c2 as deserializeProject, c3 as deserializeTimeline, c4 as diffStates, c5 as dispatch, c6 as exportToAAF, c7 as exportToEDL, c8 as exportToFCPXML, c9 as exportToOTIO, ca as findMarkersByColor, cb as findMarkersByLabel, cc as findNextClipBoundary, cd as findNextMarker, ce as findOfflineAssets, cf as findPrevClipBoundary, cg as findPrevMarker, ch as frame, ci as frameDuration, cj as frameRate, ck as frameToTimecode, cl as framesToMinutesSeconds, cm as framesToSeconds, cn as framesToTimecode, co as getActiveTool, cp as getClipDuration, cq as getClipMediaDuration, cr as getCurrentState, cs as getVisibleClips, ct as getVisibleFrameRange, cu as importFromOTIO, cv as isDropFrame, cw as isValidFrame, cx as mediaFrameForClip, cy as moveItemBetweenBins, cz as nearest, cA as nodeClock, cB as parseSRT, cC as parseVTT, cD as pushHistory, cE as redo, cF as reelName, cG as registerTool, cH as remapAssetPaths, cI as removeBin, cJ as removeItemFromBin, cK as removeTimeline, cL as resolveClip, cM as resolveFrame, cN as secondsToFrames, cO as serializeProject, cP as serializeTimeline, cQ as setProvisional, cR as sortTrackClips, cS as subtitleImportToOps, cT as subtractFrames, cU as toAssetId, cV as toBinId, cW as toClipId, cX as toEffectId, cY as toFCPTime, cZ as toFrame, c_ as toKeyframeId, c$ as toLinkGroupId, d0 as toMarkerId, d1 as toProjectId, d2 as toTimecode, d3 as toToolId, d4 as toTrackGroupId, d5 as toTrackId, d6 as toTransitionId, d7 as toggleSnap, d8 as undo } from './index-wiGRwVyY.cjs';
+
+/**
+ * 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;
+
+/**
+ * VALIDATION SYSTEM
+ *
+ * Pure functions for validating timeline state integrity.
+ *
+ * WHAT IS VALIDATION?
+ * - Checks that state meets all invariants and rules
+ * - Returns structured errors (doesn't throw exceptions)
+ * - Prevents invalid states from entering history
+ *
+ * WHY VALIDATE?
+ * - Catch errors early before they corrupt state
+ * - Provide clear error messages for debugging
+ * - Ensure timeline integrity at all times
+ *
+ * VALIDATION RULES:
+ *
+ * CLIP VALIDATION:
+ * - Asset must exist in registry
+ * - timelineEnd > timelineStart
+ * - mediaOut > mediaIn
+ * - mediaOut <= asset.intrinsicDuration
+ * - Timeline duration === media duration (Phase 1, no speed)
+ *
+ * TRACK VALIDATION:
+ * - No overlapping clips
+ * - All clips valid
+ *
+ * TIMELINE VALIDATION:
+ * - FPS > 0
+ * - Duration > 0
+ * - All tracks valid
+ *
+ * USAGE:
+ * ```typescript
+ * const result = validateClip(state, clip);
+ * if (!result.valid) {
+ *   console.error('Invalid clip:', result.errors);
+ * }
+ * ```
+ */
+
+/**
+ * Validate a clip
+ *
+ * Checks:
+ * - Asset exists
+ * - Timeline bounds are valid
+ * - Media bounds are valid
+ * - Media bounds don't exceed asset duration
+ * - Timeline duration matches media duration (Phase 1)
+ *
+ * @param state - Current timeline state
+ * @param clip - Clip to validate
+ * @returns Validation result
+ */
+declare function validateClip(state: TimelineState, clip: Clip): ValidationResult;
+/**
+ * Validate a track
+ *
+ * Checks:
+ * - No overlapping clips
+ * - All clips are valid
+ *
+ * @param state - Current timeline state
+ * @param track - Track to validate
+ * @returns Validation result
+ */
+declare function validateTrack(state: TimelineState, track: Track): ValidationResult;
+/**
+ * Validate the entire timeline
+ *
+ * Checks:
+ * - FPS is positive
+ * - Duration is positive
+ * - All tracks are valid
+ *
+ * @param state - Current timeline state
+ * @returns Validation result
+ */
+declare function validateTimeline(state: TimelineState): ValidationResult;
+/**
+ * Check if adding a clip to a track would cause overlap
+ *
+ * This is a helper for operations to check before adding a clip.
+ *
+ * @param track - Track to check
+ * @param clip - Clip to add
+ * @returns Validation result
+ */
+declare function validateNoOverlap(track: Track, clip: Clip): ValidationResult;
+
+/**
+ * QUERY SYSTEM
+ *
+ * Read-only query functions for the timeline state.
+ *
+ * WHAT ARE QUERIES?
+ * - Pure functions that read data from state
+ * - Never mutate state
+ * - Provide convenient access to timeline data
+ *
+ * WHY QUERIES?
+ * - Separate read operations from write operations
+ * - Reusable logic for finding clips, tracks, etc.
+ * - Makes the codebase easier to understand and test
+ *
+ * USAGE:
+ * ```typescript
+ * const clip = findClipById(state, 'clip_1');
+ * const track = findTrackById(state, 'track_1');
+ * const clips = getClipsAtFrame(state, frame(150));
+ * ```
+ *
+ * ALL FUNCTIONS ARE PURE AND READ-ONLY:
+ * - Take state as input
+ * - Return data (never mutate state)
+ * - No side effects
+ */
+
+/**
+ * Find a clip by ID
+ *
+ * Searches all tracks for a clip with the given ID.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to find
+ * @returns The clip, or undefined if not found
+ */
+declare function findClipById(state: TimelineState, clipId: string): Clip | undefined;
+/**
+ * Find a track by ID
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track to find
+ * @returns The track, or undefined if not found
+ */
+declare function findTrackById(state: TimelineState, trackId: string): Track | undefined;
+/**
+ * Get all clips on a specific track
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track
+ * @returns Array of clips on the track (empty if track not found)
+ */
+declare function getClipsOnTrack(state: TimelineState, trackId: string): Clip[];
+/**
+ * Get all clips at a specific frame
+ *
+ * Returns all clips that contain the given frame.
+ *
+ * @param state - Current timeline state
+ * @param frame - The frame to check
+ * @returns Array of clips at that frame
+ */
+declare function getClipsAtFrame(state: TimelineState, frame: TimelineFrame): Clip[];
+/**
+ * Get all clips in a frame range
+ *
+ * Returns all clips that overlap with the given range.
+ *
+ * @param state - Current timeline state
+ * @param start - Start frame (inclusive)
+ * @param end - End frame (exclusive)
+ * @returns Array of clips in the range
+ */
+declare function getClipsInRange(state: TimelineState, start: TimelineFrame, end: TimelineFrame): Clip[];
+/**
+ * Get all clips in the timeline
+ *
+ * @param state - Current timeline state
+ * @returns Array of all clips across all tracks
+ */
+declare function getAllClips(state: TimelineState): Clip[];
+/**
+ * Get all tracks in the timeline
+ *
+ * @param state - Current timeline state
+ * @returns Array of all tracks
+ */
+declare function getAllTracks(state: TimelineState): readonly Track[];
+/**
+ * Find the index of a track by ID
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track
+ * @returns The index of the track, or -1 if not found
+ */
+declare function findTrackIndex(state: TimelineState, trackId: string): number;
+
+/**
+ * ASSET REGISTRY SYSTEM — Phase 0 compliant
+ *
+ * Pure functions for managing assets in the timeline state.
+ * Uses state.assetRegistry (ReadonlyMap<AssetId, Asset>).
+ */
+
+declare function registerAsset(state: TimelineState, asset: Asset): TimelineState;
+declare function getAsset(state: TimelineState, assetId: string): Asset | undefined;
+declare function hasAsset(state: TimelineState, assetId: string): boolean;
+declare function getAllAssets(state: TimelineState): Asset[];
+declare function unregisterAsset(state: TimelineState, assetId: string): TimelineState;
+
+/**
+ * CLIP OPERATIONS
+ *
+ * Pure functions for manipulating clips in the timeline state.
+ *
+ * WHAT ARE OPERATIONS?
+ * - Pure functions that transform state
+ * - Take current state, return new state
+ * - Never mutate input state
+ * - No side effects
+ *
+ * WHY PURE OPERATIONS?
+ * - Predictable and testable
+ * - Can be composed together
+ * - Easy to undo/redo (just store snapshots)
+ * - No hidden state changes
+ *
+ * IMPORTANT:
+ * These operations do NOT validate. Validation happens at the
+ * dispatch layer. Operations assume inputs are valid.
+ *
+ * USAGE:
+ * ```typescript
+ * let state = addClip(state, 'track_1', clip);
+ * state = moveClip(state, 'clip_1', frame(200));
+ * state = removeClip(state, 'clip_1');
+ * ```
+ */
+
+type Frame$2 = TimelineFrame;
+/**
+ * Add a clip to a track
+ *
+ * Creates a new state with the clip added to the specified track.
+ * The track's clips are sorted by timeline start after adding.
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track to add to
+ * @param clip - Clip to add
+ * @returns New timeline state with clip added
+ */
+declare function addClip(state: TimelineState, trackId: string, clip: Clip): TimelineState;
+/**
+ * Remove a clip from the timeline
+ *
+ * Searches all tracks and removes the clip with the given ID.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to remove
+ * @returns New timeline state with clip removed
+ */
+declare function removeClip(state: TimelineState, clipId: string): TimelineState;
+/**
+ * Move a clip to a new timeline position
+ *
+ * Moves the clip by updating its timelineStart and timelineEnd.
+ * The media bounds (mediaIn/mediaOut) remain unchanged.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to move
+ * @param newStart - New timeline start frame
+ * @returns New timeline state with clip moved
+ */
+declare function moveClip(state: TimelineState, clipId: string, newStart: Frame$2): TimelineState;
+/**
+ * Resize a clip by changing its timeline bounds
+ *
+ * This adjusts the timeline bounds AND the corresponding media bounds
+ * to maintain the Phase 1 invariant: timeline duration === media duration.
+ *
+ * Left resize: Updates timelineStart and mediaIn
+ * Right resize: Updates timelineEnd and mediaOut
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to resize
+ * @param newStart - New timeline start frame
+ * @param newEnd - New timeline end frame
+ * @returns New timeline state with clip resized
+ */
+declare function resizeClip(state: TimelineState, clipId: string, newStart: Frame$2, newEnd: Frame$2): TimelineState;
+/**
+ * Trim a clip by changing its media bounds
+ *
+ * This adjusts which portion of the source asset is played.
+ * The timeline bounds remain unchanged.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to trim
+ * @param newMediaIn - New media in frame
+ * @param newMediaOut - New media out frame
+ * @returns New timeline state with clip trimmed
+ */
+declare function trimClip(state: TimelineState, clipId: string, newMediaIn: Frame$2, newMediaOut: Frame$2): TimelineState;
+/**
+ * Update clip properties
+ *
+ * Generic function to update any clip properties.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to update
+ * @param updates - Partial clip properties to update
+ * @returns New timeline state with clip updated
+ */
+declare function updateClip(state: TimelineState, clipId: string, updates: Partial<Clip>): TimelineState;
+/**
+ * Move a clip to a different track
+ *
+ * Removes the clip from its current track and adds it to the target track.
+ *
+ * If validation fails (e.g., track type mismatch), returns state unchanged.
+ * The dispatcher will catch validation errors after the operation completes.
+ *
+ * @param state - Current timeline state
+ * @param clipId - ID of the clip to move
+ * @param targetTrackId - ID of the target track
+ * @returns New timeline state with clip moved to new track, or unchanged state if validation fails
+ */
+declare function moveClipToTrack(state: TimelineState, clipId: string, targetTrackId: string): TimelineState;
+
+/**
+ * TRACK OPERATIONS
+ *
+ * Pure functions for manipulating tracks in the timeline state.
+ *
+ * WHAT ARE TRACK OPERATIONS?
+ * - Add/remove tracks
+ * - Reorder tracks
+ * - Update track properties (name, mute, lock)
+ *
+ * ALL OPERATIONS ARE PURE:
+ * - Take state as input
+ * - Return new state as output
+ * - Never mutate input state
+ *
+ * USAGE:
+ * ```typescript
+ * let state = addTrack(state, track);
+ * state = moveTrack(state, 'track_1', 2);
+ * state = updateTrack(state, 'track_1', { muted: true });
+ * state = removeTrack(state, 'track_1');
+ * ```
+ */
+
+/**
+ * Add a track to the timeline
+ *
+ * Adds the track to the end of the tracks array (top layer).
+ *
+ * @param state - Current timeline state
+ * @param track - Track to add
+ * @returns New timeline state with track added
+ */
+declare function addTrack(state: TimelineState, track: Track): TimelineState;
+/**
+ * Remove a track from the timeline
+ *
+ * WARNING: This also removes all clips on the track.
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track to remove
+ * @returns New timeline state with track removed
+ */
+declare function removeTrack(state: TimelineState, trackId: string): TimelineState;
+/**
+ * Move a track to a new position
+ *
+ * Changes the track order (bottom-to-top rendering).
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track to move
+ * @param newIndex - New index position (0 = bottom)
+ * @returns New timeline state with track moved
+ */
+declare function moveTrack(state: TimelineState, trackId: string, newIndex: number): TimelineState;
+/**
+ * Update track properties
+ *
+ * Generic function to update any track properties.
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track to update
+ * @param updates - Partial track properties to update
+ * @returns New timeline state with track updated
+ */
+declare function updateTrack(state: TimelineState, trackId: string, updates: Partial<Track>): TimelineState;
+/**
+ * Toggle track mute
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track
+ * @returns New timeline state with track mute toggled
+ */
+declare function toggleTrackMute(state: TimelineState, trackId: string): TimelineState;
+/**
+ * Toggle track lock
+ *
+ * @param state - Current timeline state
+ * @param trackId - ID of the track
+ * @returns New timeline state with track lock toggled
+ */
+declare function toggleTrackLock(state: TimelineState, trackId: string): TimelineState;
+
+/**
+ * TIMELINE OPERATIONS
+ *
+ * Pure functions for manipulating timeline-level properties.
+ *
+ * WHAT ARE TIMELINE OPERATIONS?
+ * - Update timeline duration
+ * - Update timeline name
+ * - Update timeline metadata
+ *
+ * ALL OPERATIONS ARE PURE:
+ * - Take state as input
+ * - Return new state as output
+ * - Never mutate input state
+ *
+ * USAGE:
+ * ```typescript
+ * let state = setTimelineDuration(state, frame(9000));
+ * state = setTimelineName(state, 'My Project');
+ * ```
+ */
+
+type Frame$1 = TimelineFrame;
+/**
+ * Set the timeline duration
+ *
+ * @param state - Current timeline state
+ * @param duration - New duration in frames
+ * @returns New timeline state with updated duration
+ */
+declare function setTimelineDuration(state: TimelineState, duration: Frame$1): TimelineState;
+/**
+ * Set the timeline name
+ *
+ * @param state - Current timeline state
+ * @param name - New timeline name
+ * @returns New timeline state with updated name
+ */
+declare function setTimelineName(state: TimelineState, name: string): TimelineState;
+
+/**
+ * RIPPLE OPERATIONS
+ *
+ * Ripple edits shift subsequent clips on the same track.
+ * These compose basic operations using transactions.
+ *
+ * DESIGN:
+ * - Use transactions to batch multiple moves
+ * - Only affect clips on the same track
+ * - Preserve Phase 1 collision rules
+ * - Pure functions - no mutations
+ */
+
+type Frame = TimelineFrame;
+
+/**
+ * Ripple delete - delete clip and shift all subsequent clips left
+ *
+ * @param state - Timeline state
+ * @param clipId - Clip ID to delete
+ * @returns New state with clip deleted and subsequent clips shifted
+ */
+declare function rippleDelete(state: TimelineState, clipId: string): TimelineState;
+/**
+ * Ripple trim - trim clip end and shift all subsequent clips
+ *
+ * @param state - Timeline state
+ * @param clipId - Clip ID to trim
+ * @param newEnd - New end frame for the clip
+ * @returns New state with clip trimmed and subsequent clips shifted
+ */
+declare function rippleTrim(state: TimelineState, clipId: string, newEnd: Frame): TimelineState;
+/**
+ * Insert edit - insert clip and shift all subsequent clips right
+ *
+ * @param state - Timeline state
+ * @param trackId - Track ID to insert into
+ * @param clip - Clip to insert
+ * @param atFrame - Frame to insert at
+ * @returns New state with clip inserted and subsequent clips shifted
+ */
+declare function insertEdit(state: TimelineState, trackId: string, clip: Clip, atFrame: Frame): TimelineState;
+/**
+ * Ripple move - move clip to new position with automatic gap/shift handling
+ *
+ * SEMANTICS (based on test contract):
+ *
+ * Moving RIGHT (newStart > originalStart):
+ *   - Leaves gap at source
+ *   - All clips at/after originalEnd shift RIGHT by clipDuration
+ *   - Target clip moves to newStart
+ *
+ * Moving LEFT (newStart < originalStart):
+ *   - Closes gap at source
+ *   - All clips at/after originalEnd shift LEFT by clipDuration
+ *   - Target clip moves to newStart
+ *
+ * @param state - Timeline state
+ * @param clipId - Clip ID to move
+ * @param newStart - New start frame for the clip
+ * @returns New state with clip moved and surrounding clips adjusted
+ */
+declare function rippleMove(state: TimelineState, clipId: string, newStart: Frame): TimelineState;
+/**
+ * Insert move - move clip to new position and shift destination clips right
+ *
+ * This differs from ripple move:
+ * - Ripple move: closes gap at source, swaps with intermediate clips
+ * - Insert move: leaves gap at source, pushes all destination clips right
+ *
+ * This is useful for "inserting" a clip into a specific position without
+ * affecting the source timeline structure.
+ *
+ * All operations are atomic via transaction.
+ *
+ * @param state - Timeline state
+ * @param clipId - Clip ID to move
+ * @param newStart - New start frame for the clip
+ * @returns New state with clip moved and destination clips shifted
+ *
+ * @example
+ * // Timeline before: [A][B*][C]__[D]
+ * // Insert move B to position after D
+ * // Timeline after: [A]__[C][D][B*]  (gap remains at A)
+ */
+declare function insertMove(state: TimelineState, clipId: string, newStart: Frame): TimelineState;
+
+/**
+ * ID GENERATION UTILITIES
+ *
+ * Simple, deterministic ID generation for timeline entities.
+ *
+ * WHY SIMPLE IDS?
+ * - Easy to debug (readable IDs like "clip_1", "track_2")
+ * - Deterministic for testing (can reset counter)
+ * - No external dependencies (no UUID library needed)
+ *
+ * USAGE:
+ * ```typescript
+ * const clipId = generateClipId();  // "clip_1"
+ * const trackId = generateTrackId();  // "track_1"
+ *
+ * // For testing, you can reset the counter
+ * resetIdCounter();
+ * ```
+ *
+ * NOTE: In production, you might want to use UUIDs or other
+ * globally unique identifiers. This simple system is sufficient
+ * for Phase 1 and makes debugging easier.
+ */
+/**
+ * Generate a unique ID with a given prefix
+ *
+ * @param prefix - Prefix for the ID (e.g., "clip", "track")
+ * @returns A unique ID string
+ */
+declare function generateId(prefix: string): string;
+/**
+ * Generate a unique clip ID
+ *
+ * @returns A unique clip ID (e.g., "clip_1")
+ */
+declare function generateClipId(): string;
+/**
+ * Generate a unique track ID
+ *
+ * @returns A unique track ID (e.g., "track_1")
+ */
+declare function generateTrackId(): string;
+/**
+ * Generate a unique timeline ID
+ *
+ * @returns A unique timeline ID (e.g., "timeline_1")
+ */
+declare function generateTimelineId(): string;
+/**
+ * Generate a unique asset ID
+ *
+ * @returns A unique asset ID (e.g., "asset_1")
+ */
+declare function generateAssetId(): string;
+/**
+ * Reset the ID counter
+ *
+ * This is useful for testing to ensure deterministic IDs.
+ * DO NOT use this in production code.
+ */
+declare function resetIdCounter(): void;
+
+/**
+ * ID GENERATION UTILITIES - PHASE 2
+ *
+ * Additional ID generators for Phase 2 features.
+ */
+/**
+ * Generate a unique link group ID
+ *
+ * @returns A unique link group ID
+ */
+declare function generateLinkGroupId(): string;
+/**
+ * Generate a unique group ID
+ *
+ * @returns A unique group ID
+ */
+declare function generateGroupId(): string;
+/**
+ * Generate a unique marker ID
+ *
+ * @returns A unique marker ID
+ */
+declare function generateMarkerId(): string;
+
+export { Asset, Clip, TimelineFrame as Frame, TimelineFrame, TimelineState, Track, addClip, addTrack, combineResults, findClipById, findTrackById, findTrackIndex, generateAssetId, generateClipId, generateGroupId, generateId, generateLinkGroupId, generateMarkerId, generateTimelineId, generateTrackId, getAllAssets, getAllClips, getAllTracks, getAsset, getClipsAtFrame, getClipsInRange, getClipsOnTrack, hasAsset, insertEdit, insertMove, invalidResult, invalidResults, moveClip, moveClipToTrack, moveTrack, registerAsset, removeClip, removeTrack, resetIdCounter, resizeClip, rippleDelete, rippleMove, rippleTrim, setTimelineDuration, setTimelineName, toggleTrackLock, toggleTrackMute, trimClip, unregisterAsset, updateClip, updateTrack, validResult, validateClip, validateNoOverlap, validateTimeline, validateTrack };