@webpacked-timeline/core 1.0.0-beta.1

package/dist/index-B2m3zwg7.d.ts

@@ -0,0 +1,1381 @@
+/**
+ * FRAME-BASED TIME REPRESENTATION
+ *
+ * Phase 0 compliant. All time values in state are TimelineFrame branded integers.
+ * FrameRate is a discriminated literal union — never a raw float.
+ *
+ * THREE INVIOLABLE RULES:
+ * 1. Core has ZERO UI framework imports.
+ * 2. Every function that changes state returns a NEW object.
+ * 3. Every frame value is a branded TimelineFrame integer — never a raw number.
+ */
+/**
+ * TimelineFrame — A discrete, non-negative integer point in time measured in frames.
+ *
+ * Branded so TypeScript prevents raw numbers from sneaking into frame positions.
+ * The ONLY way to create one is via toFrame().
+ */
+type TimelineFrame = number & {
+    readonly __brand: "TimelineFrame";
+};
+/** The canonical factory. Use this everywhere instead of casting. */
+declare const toFrame: (n: number) => TimelineFrame;
+/**
+ * Legacy alias kept for backward-compat during transition.
+ * Prefer toFrame() for new code.
+ */
+declare function frame(value: number): TimelineFrame;
+/**
+ * FrameRate — The exact set of supported frame rates.
+ *
+ * RULE: Never pass 29.97 as a plain number. Use the literal type.
+ * This is a discriminated union — TypeScript enforces membership at compile time.
+ */
+type FrameRate = 23.976 | 24 | 25 | 29.97 | 30 | 50 | 59.94 | 60;
+/**
+ * Named constants for the most common rates.
+ * Prefer these over raw literals where possible.
+ */
+declare const FrameRates: {
+    readonly CINEMA: FrameRate;
+    readonly PAL: FrameRate;
+    readonly NTSC_DF: FrameRate;
+    readonly NTSC: FrameRate;
+    readonly PAL_HFR: FrameRate;
+    readonly NTSC_HFR: FrameRate;
+    readonly HFR: FrameRate;
+};
+/**
+ * Legacy factory — kept for backward-compat with existing tests.
+ * This now validates that the value is a member of the FrameRate union.
+ * @throws if the value is not a recognised frame rate.
+ */
+declare function frameRate(value: number): FrameRate;
+/**
+ * RationalTime — a frame count at a specific rate. Used only at
+ * ingest/export boundaries. Never stored in TimelineState.
+ */
+type RationalTime = {
+    readonly value: number;
+    readonly rate: FrameRate;
+};
+/**
+ * Timecode — SMPTE timecode string, display-only. Never use for arithmetic.
+ */
+type Timecode = string & {
+    readonly __brand: "Timecode";
+};
+declare const toTimecode: (s: string) => Timecode;
+/**
+ * TimeRange — a start + duration pair, both in TimelineFrame units.
+ */
+type TimeRange = {
+    readonly startFrame: TimelineFrame;
+    readonly duration: TimelineFrame;
+};
+declare function isValidFrame(value: number): boolean;
+declare function isDropFrame(fps: FrameRate): boolean;
+
+/**
+ * ASSET MODEL — Phase 0 compliant
+ *
+ * Asset is immutable metadata about a media source file.
+ * Multiple Clips can reference the same Asset.
+ * Assets never change their intrinsicDuration after registration.
+ */
+
+type AssetId = string & {
+    readonly __brand: 'AssetId';
+};
+type AssetStatus = 'online' | 'offline' | 'proxy-only' | 'missing';
+/**
+ * Asset — immutable metadata for a single media source file.
+ *
+ * RULE: Never store wall-clock seconds or floating-point durations here.
+ * intrinsicDuration is always a TimelineFrame measured at the timeline fps.
+ */
+type Asset = {
+    readonly id: AssetId;
+    readonly name: string;
+    /**
+     * mediaType must match the type of any Track this asset's clips are placed on.
+     * Replaces the old 'type: AssetType' field.
+     */
+    readonly mediaType: TrackType;
+    /** Replaces the old 'sourceUrl: string' field. */
+    readonly filePath: string;
+    /** Total length of the source media, expressed as TimelineFrame at the timeline fps. */
+    readonly intrinsicDuration: TimelineFrame;
+    /** The native frame rate the file was captured at. */
+    readonly nativeFps: FrameRate;
+    /** Where in the source the first frame maps to on the timeline. */
+    readonly sourceTimecodeOffset: TimelineFrame;
+    readonly status: AssetStatus;
+};
+declare function createAsset(params: {
+    id: string;
+    name: string;
+    mediaType: TrackType;
+    filePath: string;
+    intrinsicDuration: TimelineFrame;
+    nativeFps: FrameRate;
+    sourceTimecodeOffset: TimelineFrame;
+    status?: AssetStatus;
+}): Asset;
+
+/**
+ * CLIP MODEL — Phase 0 compliant
+ *
+ * A Clip is a time-bound reference to an Asset placed on a Track.
+ * All fields are readonly. Never mutate — always return a new object.
+ */
+
+type ClipId = string & {
+    readonly __brand: 'ClipId';
+};
+/**
+ * Clip — a time-bound viewport into an Asset on a Track.
+ *
+ * TIMELINE BOUNDS: timelineStart / timelineEnd — where it sits on the track.
+ * MEDIA BOUNDS:    mediaIn / mediaOut         — which portion of the asset plays.
+ *
+ * INVARIANTS (Phase 0, speed=1.0):
+ *   timelineEnd > timelineStart
+ *   mediaOut > mediaIn
+ *   (mediaOut - mediaIn) === (timelineEnd - timelineStart)
+ *   mediaIn >= 0
+ *   mediaOut <= asset.intrinsicDuration
+ *   timelineEnd <= timeline.duration
+ *   speed > 0
+ */
+type Clip = {
+    readonly id: ClipId;
+    readonly assetId: AssetId;
+    readonly trackId: TrackId;
+    readonly timelineStart: TimelineFrame;
+    readonly timelineEnd: TimelineFrame;
+    readonly mediaIn: TimelineFrame;
+    readonly mediaOut: TimelineFrame;
+    readonly speed: number;
+    readonly enabled: boolean;
+    readonly reversed: boolean;
+    readonly name: string | null;
+    readonly color: string | null;
+    readonly metadata: Record<string, string>;
+};
+declare function createClip(params: {
+    id: string;
+    assetId: string;
+    trackId: string;
+    timelineStart: TimelineFrame;
+    timelineEnd: TimelineFrame;
+    mediaIn: TimelineFrame;
+    mediaOut: TimelineFrame;
+    speed?: number;
+    enabled?: boolean;
+    reversed?: boolean;
+    name?: string | null;
+    color?: string | null;
+    metadata?: Record<string, string>;
+}): Clip;
+declare function getClipDuration(clip: Clip): TimelineFrame;
+declare function getClipMediaDuration(clip: Clip): TimelineFrame;
+declare function clipContainsFrame(clip: Clip, f: TimelineFrame): boolean;
+declare function clipsOverlap(a: Clip, b: Clip): boolean;
+
+/**
+ * TRACK MODEL — Phase 0 compliant
+ *
+ * A Track is a horizontal container for Clips, always sorted by timelineStart.
+ */
+
+type TrackId = string & {
+    readonly __brand: 'TrackId';
+};
+type TrackType = 'video' | 'audio' | 'subtitle' | 'title';
+type Track = {
+    readonly id: TrackId;
+    readonly name: string;
+    readonly type: TrackType;
+    readonly locked: boolean;
+    readonly muted: boolean;
+    readonly solo: boolean;
+    readonly height: number;
+    /** Always sorted ascending by timelineStart — invariant enforced by checkInvariants. */
+    readonly clips: readonly Clip[];
+};
+declare function createTrack(params: {
+    id: string;
+    name: string;
+    type: TrackType;
+    clips?: readonly Clip[];
+    locked?: boolean;
+    muted?: boolean;
+    solo?: boolean;
+    height?: number;
+}): Track;
+/** Returns a new track with clips sorted ascending by timelineStart. */
+declare function sortTrackClips(track: Track): Track;
+
+/**
+ * TIMELINE MODEL — Phase 0 compliant
+ */
+
+type SequenceSettings = {
+    readonly pixelAspectRatio: number;
+    readonly fieldOrder: 'progressive' | 'upper' | 'lower';
+    readonly colorSpace: string;
+    readonly audioSampleRate: number;
+    readonly audioChannelCount: number;
+};
+type Timeline = {
+    readonly id: string;
+    readonly name: string;
+    readonly fps: FrameRate;
+    readonly duration: TimelineFrame;
+    readonly startTimecode: Timecode;
+    readonly tracks: readonly Track[];
+    readonly sequenceSettings: SequenceSettings;
+    /**
+     * Increments by 1 on every successfully committed Transaction.
+     * Use this to detect stale references without deep equality checks.
+     */
+    readonly version: number;
+};
+declare function createTimeline(params: {
+    id: string;
+    name: string;
+    fps: FrameRate;
+    duration: TimelineFrame;
+    startTimecode?: Timecode;
+    tracks?: readonly Track[];
+    sequenceSettings?: Partial<SequenceSettings>;
+}): Timeline;
+
+/**
+ * TIMELINE STATE — Phase 0 compliant
+ *
+ * TimelineState is the single source of truth for the engine.
+ * Phase 0 only: timeline + assetRegistry. No Phase 2 fields.
+ *
+ * RULE: Every function that changes state returns a NEW TimelineState.
+ * Never mutate the existing state.
+ */
+
+type AssetRegistry = ReadonlyMap<AssetId, Asset>;
+type TimelineState = {
+    readonly timeline: Timeline;
+    readonly assetRegistry: AssetRegistry;
+};
+declare function createTimelineState(params: {
+    timeline: Timeline;
+    assetRegistry?: AssetRegistry;
+    /** @deprecated use assetRegistry. Kept for test backward-compat only. */
+    assets?: Map<string, Asset>;
+}): TimelineState;
+
+/**
+ * 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: TimelineFrame, 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): TimelineFrame;
+/**
+ * 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: TimelineFrame, 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: TimelineFrame, 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: TimelineFrame, min: TimelineFrame, max: TimelineFrame): TimelineFrame;
+/**
+ * Add two frame values
+ *
+ * @param a - First frame
+ * @param b - Second frame
+ * @returns Sum of frames
+ */
+declare function addFrames(a: TimelineFrame, b: TimelineFrame): TimelineFrame;
+/**
+ * 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: TimelineFrame, b: TimelineFrame): TimelineFrame;
+/**
+ * Calculate duration between two frames
+ *
+ * @param start - Start frame
+ * @param end - End frame
+ * @returns Duration in frames (end - start)
+ */
+declare function frameDuration(start: TimelineFrame, end: TimelineFrame): TimelineFrame;
+
+/**
+ * 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): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Remove a clip
+     *
+     * @param clipId - ID of the clip to remove
+     * @returns Dispatch result
+     */
+    removeClip(clipId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame, newEnd: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame, newMediaOut: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Add a track
+     *
+     * @param track - Track to add
+     * @returns Dispatch result
+     */
+    addTrack(track: Track): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Remove a track
+     *
+     * @param trackId - ID of the track to remove
+     * @returns Dispatch result
+     */
+    removeTrack(trackId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Toggle track mute
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackMute(trackId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Toggle track lock
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackLock(trackId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Toggle track solo
+     *
+     * @param trackId - ID of the track
+     * @returns Dispatch result
+     */
+    toggleTrackSolo(trackId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Set track height
+     *
+     * @param trackId - ID of the track
+     * @param height - New height in pixels
+     * @returns Dispatch result
+     */
+    setTrackHeight(trackId: string, height: number): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Set timeline duration
+     *
+     * @param duration - New duration in frames
+     * @returns Dispatch result
+     */
+    setTimelineDuration(duration: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * Set timeline name
+     *
+     * @param name - New timeline name
+     * @returns Dispatch result
+     */
+    setTimelineName(name: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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(f: TimelineFrame): 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: TimelineFrame, end: TimelineFrame): 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(): readonly Track[];
+    /**
+     * Ripple delete - delete clip and shift subsequent clips left
+     *
+     * @param clipId - ID of the clip to delete
+     * @returns Dispatch result
+     */
+    rippleDelete(clipId: string): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+    /**
+     * 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: TimelineFrame): {
+        accepted: boolean;
+        errors?: {
+            code: string;
+            message: string;
+        }[];
+    };
+}
+
+/**
+ * OPERATION PRIMITIVES — Phase 0 compliant
+ *
+ * The ONLY way to express a mutation in the engine.
+ * All mutations flow through: OperationPrimitive[] → Transaction → Dispatcher.
+ *
+ * RULE: Never add a new mutation function.
+ *       Add a new type to OperationPrimitive, handle it in the Dispatcher switch,
+ *       update the InvariantChecker, and update OPERATIONS.md.
+ *
+ * RULE: Transactions are all-or-nothing.
+ *       If any primitive fails validation, the entire Transaction is rejected.
+ */
+
+type OperationPrimitive = {
+    type: 'MOVE_CLIP';
+    clipId: ClipId;
+    newTimelineStart: TimelineFrame;
+    targetTrackId?: TrackId;
+} | {
+    type: 'RESIZE_CLIP';
+    clipId: ClipId;
+    edge: 'start' | 'end';
+    newFrame: TimelineFrame;
+} | {
+    type: 'SLICE_CLIP';
+    clipId: ClipId;
+    atFrame: TimelineFrame;
+} | {
+    type: 'DELETE_CLIP';
+    clipId: ClipId;
+} | {
+    type: 'INSERT_CLIP';
+    clip: Clip;
+    trackId: TrackId;
+} | {
+    type: 'SET_MEDIA_BOUNDS';
+    clipId: ClipId;
+    mediaIn: TimelineFrame;
+    mediaOut: TimelineFrame;
+} | {
+    type: 'SET_CLIP_ENABLED';
+    clipId: ClipId;
+    enabled: boolean;
+} | {
+    type: 'SET_CLIP_REVERSED';
+    clipId: ClipId;
+    reversed: boolean;
+} | {
+    type: 'SET_CLIP_SPEED';
+    clipId: ClipId;
+    speed: number;
+} | {
+    type: 'SET_CLIP_COLOR';
+    clipId: ClipId;
+    color: string | null;
+} | {
+    type: 'SET_CLIP_NAME';
+    clipId: ClipId;
+    name: string | null;
+} | {
+    type: 'ADD_TRACK';
+    track: Track;
+} | {
+    type: 'DELETE_TRACK';
+    trackId: TrackId;
+} | {
+    type: 'REORDER_TRACK';
+    trackId: TrackId;
+    newIndex: number;
+} | {
+    type: 'SET_TRACK_HEIGHT';
+    trackId: TrackId;
+    height: number;
+} | {
+    type: 'SET_TRACK_NAME';
+    trackId: TrackId;
+    name: string;
+} | {
+    type: 'REGISTER_ASSET';
+    asset: Asset;
+} | {
+    type: 'UNREGISTER_ASSET';
+    assetId: AssetId;
+} | {
+    type: 'SET_ASSET_STATUS';
+    assetId: AssetId;
+    status: AssetStatus;
+} | {
+    type: 'RENAME_TIMELINE';
+    name: string;
+} | {
+    type: 'SET_TIMELINE_DURATION';
+    duration: TimelineFrame;
+} | {
+    type: 'SET_TIMELINE_START_TC';
+    startTimecode: Timecode;
+} | {
+    type: 'SET_SEQUENCE_SETTINGS';
+    settings: Partial<SequenceSettings>;
+};
+/**
+ * Transaction — an atomic, labeled batch of OperationPrimitives.
+ *
+ * All primitives in a Transaction are validated before any are applied.
+ * If one fails, none are applied. This is the all-or-nothing rule.
+ */
+type Transaction = {
+    readonly id: string;
+    readonly label: string;
+    readonly timestamp: number;
+    readonly operations: readonly OperationPrimitive[];
+};
+type RejectionReason = 'OVERLAP' | 'LOCKED_TRACK' | 'ASSET_MISSING' | 'TYPE_MISMATCH' | 'OUT_OF_BOUNDS' | 'MEDIA_BOUNDS_INVALID' | 'ASSET_IN_USE' | 'TRACK_NOT_EMPTY' | 'SPEED_INVALID' | 'INVARIANT_VIOLATED';
+type DispatchResult = {
+    accepted: true;
+    nextState: TimelineState;
+} | {
+    accepted: false;
+    reason: RejectionReason;
+    message: string;
+};
+type ViolationType = 'OVERLAP' | 'MEDIA_BOUNDS_INVALID' | 'ASSET_MISSING' | 'TRACK_TYPE_MISMATCH' | 'CLIP_BEYOND_TIMELINE' | 'TRACK_NOT_SORTED' | 'DURATION_MISMATCH' | 'SPEED_INVALID';
+type InvariantViolation = {
+    readonly type: ViolationType;
+    readonly entityId: string;
+    readonly message: string;
+};
+
+/**
+ * DISPATCHER — Phase 0 compliant
+ *
+ * The ONLY entry point for mutating TimelineState.
+ * Validates first, applies atomically, checks invariants.
+ *
+ * Algorithm:
+ * 1. For each operation: run per-primitive validator → reject immediately on failure
+ * 2. Apply all operations sequentially to get proposedState
+ * 3. Run checkInvariants(proposedState) → reject on any violation
+ * 4. Bump timeline.version by 1 and return accepted
+ *
+ * RULE: If one primitive fails, zero primitives are applied.
+ */
+
+declare function dispatch(state: TimelineState, transaction: Transaction): DispatchResult;
+
+/**
+ * INVARIANT CHECKER — Phase 0 compliant
+ *
+ * The most critical file in the engine.
+ * checkInvariants() runs after every proposed state change inside the Dispatcher.
+ * Zero violations is the only acceptable result in tests and at commit time.
+ *
+ * RULE: Run checkInvariants in EVERY test after every state mutation.
+ */
+
+declare function checkInvariants(state: TimelineState): InvariantViolation[];
+
+/**
+ * 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;
+}
+/**
+ * Create a new history state
+ *
+ * @param initialState - Initial timeline state
+ * @param limit - Maximum number of past states to keep (default: 50)
+ * @returns A new HistoryState
+ */
+declare function createHistory(initialState: TimelineState, limit?: number): HistoryState;
+/**
+ * Push a new state to history
+ *
+ * Moves current state to past, sets new state as present,
+ * and clears future (can't redo after new action).
+ *
+ * @param history - Current history state
+ * @param newState - New timeline state to push
+ * @returns New history state with new state pushed
+ */
+declare function pushHistory(history: HistoryState, newState: TimelineState): HistoryState;
+/**
+ * Undo the last action
+ *
+ * Moves current state to future, pops last state from past
+ * and sets it as present.
+ *
+ * @param history - Current history state
+ * @returns New history state with undo applied
+ */
+declare function undo(history: HistoryState): HistoryState;
+/**
+ * Redo the last undone action
+ *
+ * Moves current state to past, pops first state from future
+ * and sets it as present.
+ *
+ * @param history - Current history state
+ * @returns New history state with redo applied
+ */
+declare function redo(history: HistoryState): HistoryState;
+/**
+ * Check if undo is available
+ *
+ * @param history - Current history state
+ * @returns true if undo is available
+ */
+declare function canUndo(history: HistoryState): boolean;
+/**
+ * Check if redo is available
+ *
+ * @param history - Current history state
+ * @returns true if redo is available
+ */
+declare function canRedo(history: HistoryState): boolean;
+/**
+ * Get the current state from history
+ *
+ * @param history - Current history state
+ * @returns The current timeline state
+ */
+declare function getCurrentState(history: HistoryState): TimelineState;
+
+/**
+ * SNAP INDEX — Phase 1
+ *
+ * Pure functions. Zero React/DOM imports. Zero mutation.
+ *
+ * Phase 1 snap sources: ClipStart, ClipEnd, Playhead.
+ * Phase 2 will add: Marker, InPoint, OutPoint.
+ * Phase 3 will add: BeatGrid.
+ *
+ * Priority table (do not change values):
+ *   Marker:    100
+ *   InPoint:    90
+ *   OutPoint:   90
+ *   ClipStart:  80
+ *   ClipEnd:    80
+ *   Playhead:   70
+ *   BeatGrid:   50
+ */
+
+/**
+ * All snap point sources across phases.
+ * Defined in full now so SnapPoint & allowedTypes filters are stable.
+ */
+type SnapPointType = 'ClipStart' | 'ClipEnd' | 'Playhead' | 'Marker' | 'InPoint' | 'OutPoint' | 'BeatGrid';
+type SnapPoint = {
+    readonly frame: TimelineFrame;
+    readonly type: SnapPointType;
+    readonly priority: number;
+    readonly trackId: TrackId | null;
+    readonly sourceId: string;
+};
+type SnapIndex = {
+    readonly points: readonly SnapPoint[];
+    readonly builtAt: number;
+    readonly enabled: boolean;
+};
+/**
+ * Build a SnapIndex from committed state + playhead position.
+ *
+ * RULE: Call via queueMicrotask after accepted dispatch.
+ *       Never call during a drag (pointer move).
+ *
+ * Phase 1 sources pulled (in order):
+ *   1. ClipStart + ClipEnd from every clip on every track
+ *   2. Playhead position (trackId = null)
+ */
+declare function buildSnapIndex(state: TimelineState, playheadFrame: TimelineFrame, enabled?: boolean): SnapIndex;
+/**
+ * Find the highest-priority snap candidate within radiusFrames.
+ *
+ * Returns null when:
+ *   - index.enabled is false
+ *   - no point is within radiusFrames of frame
+ *
+ * Tiebreak (equidistant candidates): highest priority wins.
+ * Second tiebreak (equal priority): first in sorted order.
+ *
+ * @param exclude      sourceIds to skip (e.g. the clip being dragged)
+ * @param allowedTypes if provided, only consider points of these types
+ */
+declare function nearest(index: SnapIndex, frame: TimelineFrame, radiusFrames: number, exclude?: readonly string[], allowedTypes?: readonly SnapPointType[]): SnapPoint | null;
+/**
+ * Return a new SnapIndex with enabled toggled.
+ * Does NOT rebuild points — pure field update.
+ */
+declare function toggleSnap(index: SnapIndex, enabled: boolean): SnapIndex;
+
+/**
+ * TOOL CONTRACT TYPES — Phase 1
+ *
+ * Zero implementation. Zero imports from React or DOM.
+ * Every ITool must satisfy this interface exactly.
+ *
+ * RULES (from ITOOL_CONTRACT.md):
+ *   - onPointerMove NEVER calls dispatch
+ *   - onPointerUp NEVER mutates instance state
+ *   - onKeyDown, onKeyUp, onCancel are REQUIRED — implement as no-ops if unused
+ */
+
+type ToolId = string & {
+    readonly __brand: 'ToolId';
+};
+declare function toToolId(s: string): ToolId;
+/** Keyboard modifier state — available on ToolContext so getCursor() can
+ *  react to held keys even when no pointer event is firing. */
+type Modifiers = {
+    readonly shift: boolean;
+    readonly alt: boolean;
+    readonly ctrl: boolean;
+    readonly meta: boolean;
+};
+/** Normalised pointer event in frame-space.
+ *  ToolRouter populates clipId via hit-test — tools never recompute it. */
+type TimelinePointerEvent = {
+    readonly frame: TimelineFrame;
+    readonly trackId: TrackId | null;
+    readonly clipId: ClipId | null;
+    readonly x: number;
+    readonly y: number;
+    readonly buttons: number;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+};
+type TimelineKeyEvent = {
+    readonly key: string;
+    readonly code: string;
+    readonly shiftKey: boolean;
+    readonly altKey: boolean;
+    readonly metaKey: boolean;
+};
+/** Ghost state produced by onPointerMove.
+ *  isProvisional: true is a compile-time discriminant so resolveClip()
+ *  can distinguish provisional from committed Clip[] arrays. */
+type ProvisionalState = {
+    readonly clips: readonly Clip[];
+    readonly isProvisional: true;
+};
+/** Injected by TimelineEngine on every event call.
+ *  Tools never import TimelineEngine. They never call dispatch() directly. */
+type ToolContext = {
+    readonly state: TimelineState;
+    readonly snapIndex: SnapIndex;
+    readonly pixelsPerFrame: number;
+    /** Current modifier key state — updates on every pointer/key event. */
+    readonly modifiers: Modifiers;
+    /** Convert a client-pixel x-position to a TimelineFrame. */
+    readonly frameAtX: (x: number) => TimelineFrame;
+    /** Return the TrackId whose row contains client-pixel y, or null. */
+    readonly trackAtY: (y: number) => TrackId | null;
+    /** Query snap and return the snapped frame (or original if no hit).
+     *  Handles enabled/disabled, radius, exclusion, and type filter internally.
+     *  Tools never see radiusFrames or the enabled flag. */
+    readonly snap: (frame: TimelineFrame, exclude?: readonly string[], allowedTypes?: readonly SnapPointType[]) => TimelineFrame;
+};
+interface ITool {
+    readonly id: ToolId;
+    /** Single-character keyboard shortcut, e.g. 'v', 'b', 'r'. Empty string = no shortcut. */
+    readonly shortcutKey: string;
+    /** Return the CSS cursor string for the current tool + modifier state.
+     *  Called on every pointermove — must be cheap. */
+    getCursor(ctx: ToolContext): string;
+    /** Return the SnapPointType categories this tool snaps to.
+     *  Used by ctx.snap() to filter the snap index automatically. */
+    getSnapCandidateTypes(): readonly SnapPointType[];
+    onPointerDown(event: TimelinePointerEvent, ctx: ToolContext): void;
+    /** Return ProvisionalState for ghost rendering.
+     *  MUST NOT call dispatch. MUST NOT call engine methods. */
+    onPointerMove(event: TimelinePointerEvent, ctx: ToolContext): ProvisionalState | null;
+    /** Return a Transaction to commit, or null if this gesture produces no edit.
+     *  MUST NOT mutate any instance state. */
+    onPointerUp(event: TimelinePointerEvent, ctx: ToolContext): Transaction | null;
+    /** Handle a keydown — return a Transaction or null.
+     *  Required — implement as `return null` if unused. */
+    onKeyDown(event: TimelineKeyEvent, ctx: ToolContext): Transaction | null;
+    /** Handle a keyup — no return value.
+     *  Required — implement as no-op if unused. */
+    onKeyUp(event: TimelineKeyEvent, ctx: ToolContext): void;
+    /** Called when a gesture is interrupted (Escape, tool switch mid-drag).
+     *  Required — implement as no-op if unused. */
+    onCancel(): void;
+}
+
+/**
+ * TOOL REGISTRY — Phase 1
+ *
+ * Pure functions. No classes. No React. No state mutation.
+ *
+ * ToolRegistry is immutable data — activateTool returns a NEW registry.
+ * The active tool lives here, not on TimelineEngine, keeping the engine thin.
+ *
+ * RULES:
+ *   - activateTool calls outgoing.onCancel() before switching
+ *   - activateTool throws on unknown id (programmer error, never user error)
+ *   - NoOpTool is the canonical do-nothing ITool (test double + startup default)
+ */
+
+type ToolRegistry = {
+    readonly tools: ReadonlyMap<ToolId, ITool>;
+    readonly activeToolId: ToolId;
+};
+/**
+ * Create an initial registry from an array of tools.
+ *
+ * @throws if defaultId is not present in the tools array
+ */
+declare function createRegistry(tools: readonly ITool[], defaultId: ToolId): ToolRegistry;
+/**
+ * Activate a new tool.
+ *
+ * Steps (must run in order):
+ *   1. Call outgoing tool's onCancel() — cleans up any in-progress drag state
+ *   2. Validate that the new id exists in the registry
+ *   3. Return a new ToolRegistry with activeToolId updated
+ *
+ * @throws if id is not registered
+ */
+declare function activateTool(registry: ToolRegistry, id: ToolId): ToolRegistry;
+/**
+ * Return the currently active ITool.
+ * Never returns undefined — registry invariant guarantees activeToolId is registered.
+ */
+declare function getActiveTool(registry: ToolRegistry): ITool;
+/**
+ * Return a new registry with the tool added.
+ * If a tool with the same id already exists, it is replaced.
+ * activeToolId is unchanged.
+ */
+declare function registerTool(registry: ToolRegistry, tool: ITool): ToolRegistry;
+/**
+ * Satisfies ITool with no side effects.
+ *
+ * Use for:
+ *   - Test doubles (spread and override only the methods you need)
+ *   - Default active tool on engine startup
+ *   - ToolRouter smoke tests
+ *
+ * onCancel() is a deliberate no-op: NoOpTool has no drag state to clean up.
+ * Real tools will clear instance variables there.
+ */
+declare const NoOpTool: ITool;
+
+/**
+ * PROVISIONAL MANAGER — Phase 1
+ *
+ * Manages ghost state during pointer drags.
+ *
+ * RULES (from ITOOL_CONTRACT.md):
+ *   - setProvisional / clearProvisional return NEW objects — never mutate
+ *   - resolveClip checks provisional first, then committed state
+ *   - The engine calls clearProvisional() BEFORE dispatching onPointerUp's tx
+ *   - Provisional updates trigger notify() so ghosts render immediately
+ *
+ * resolveClip priority:
+ *   1. provisional.clips has a clip with this id → return ghost version
+ *   2. clip exists in committed state → return committed
+ *   3. clip absent from both (deleted mid-drag) → return undefined
+ */
+
+type ProvisionalManager = {
+    readonly current: ProvisionalState | null;
+};
+/** Create an empty provisional manager (current = null). */
+declare function createProvisionalManager(): ProvisionalManager;
+/** Return a new manager with current set to state.
+ *  Pure — never mutates the original manager. */
+declare function setProvisional(_manager: ProvisionalManager, state: ProvisionalState): ProvisionalManager;
+/** Return a new manager with current set to null.
+ *  Pure — never mutates the original manager. */
+declare function clearProvisional(_manager: ProvisionalManager): ProvisionalManager;
+/**
+ * Resolve which version of a clip to render.
+ *
+ * Priority:
+ *   1. If manager.current has a clip with this id → return provisional (ghost)
+ *   2. Otherwise → search committed state
+ *   3. If absent from both (clip deleted mid-drag) → return undefined
+ *
+ * Returns undefined if the clip has been deleted from committed state
+ * and is not in provisional. Components must handle this:
+ *   const clip = useClip(id)
+ *   if (!clip) return null  ← required, not optional
+ *
+ * Call site in useClip selector:
+ *   () => resolveClip(id, engine.getSnapshot(), engine.getProvisionalManager())
+ */
+declare function resolveClip(clipId: ClipId, state: TimelineState, manager: ProvisionalManager): Clip | undefined;
+
+export { createRegistry as $, type Asset as A, addFrames as B, type Clip as C, type DispatchResult as D, buildSnapIndex as E, type FrameRate as F, canRedo as G, type HistoryState as H, type ITool as I, canUndo as J, checkInvariants as K, clampFrame as L, type Modifiers as M, NoOpTool as N, type OperationPrimitive as O, type ProvisionalManager as P, clearProvisional as Q, type RationalTime as R, type SequenceSettings as S, type TimelineState as T, clipContainsFrame as U, type ViolationType as V, clipsOverlap as W, createAsset as X, createClip as Y, createHistory as Z, createProvisionalManager as _, type Track as a, createTimeline as a0, createTimelineState as a1, createTrack as a2, dispatch as a3, frame as a4, frameDuration as a5, frameRate as a6, framesToMinutesSeconds as a7, framesToSeconds as a8, framesToTimecode as a9, getActiveTool as aa, getClipDuration as ab, getClipMediaDuration as ac, getCurrentState as ad, isDropFrame as ae, isValidFrame as af, nearest as ag, pushHistory as ah, redo as ai, registerTool as aj, resolveClip as ak, secondsToFrames as al, setProvisional as am, sortTrackClips as an, subtractFrames as ao, toFrame as ap, toTimecode as aq, toToolId as ar, toggleSnap as as, undo as at, type TimelineFrame as b, type AssetId as c, type AssetRegistry as d, type AssetStatus as e, type ClipId as f, FrameRates as g, type InvariantViolation as h, type ProvisionalState as i, type RejectionReason as j, type SnapIndex as k, type SnapPoint as l, type SnapPointType as m, type TimeRange as n, type Timecode as o, type Timeline as p, TimelineEngine as q, type TimelineKeyEvent as r, type TimelinePointerEvent as s, type ToolContext as t, type ToolId as u, type ToolRegistry as v, type TrackId as w, type TrackType as x, type Transaction as y, activateTool as z };