@webpacked-timeline/core 1.0.0-beta.1

package/dist/index-DrOA6QmW.d.cts

@@ -0,0 +1,2492 @@
+/**
+ * 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;
+
+/**
+ * GENERATOR MODEL — Phase 3
+ *
+ * Generators are synthetic "assets" (solid, bars, countdown, etc.)
+ * registered in AssetRegistry as GeneratorAsset. No filePath.
+ */
+
+type GeneratorId = string & {
+    readonly __brand: 'GeneratorId';
+};
+type GeneratorType = 'solid' | 'bars' | 'countdown' | 'noise' | 'text';
+type Generator = {
+    readonly id: GeneratorId;
+    readonly type: GeneratorType;
+    readonly params: Record<string, unknown>;
+    readonly duration: TimelineFrame;
+    readonly name: string;
+};
+
+/**
+ * ASSET MODEL — Phase 0 + Phase 3
+ *
+ * Asset is FileAsset | GeneratorAsset. Multiple Clips can reference the same Asset.
+ * Assets never change their intrinsicDuration after registration.
+ */
+
+type AssetId = string & {
+    readonly __brand: 'AssetId';
+};
+declare const toAssetId: (s: string) => AssetId;
+type AssetStatus = 'online' | 'offline' | 'proxy-only' | 'missing';
+type FileAsset = {
+    readonly kind: 'file';
+    readonly id: AssetId;
+    readonly name: string;
+    readonly mediaType: TrackType;
+    readonly filePath: string;
+    readonly intrinsicDuration: TimelineFrame;
+    readonly nativeFps: FrameRate;
+    readonly sourceTimecodeOffset: TimelineFrame;
+    readonly status: AssetStatus;
+};
+type GeneratorAsset = {
+    readonly kind: 'generator';
+    readonly id: AssetId;
+    readonly name: string;
+    readonly mediaType: TrackType;
+    readonly intrinsicDuration: TimelineFrame;
+    readonly nativeFps: FrameRate;
+    readonly sourceTimecodeOffset: TimelineFrame;
+    readonly status: AssetStatus;
+    readonly generatorDef: Generator;
+};
+type Asset = FileAsset | GeneratorAsset;
+declare function createAsset(params: {
+    id: string;
+    name: string;
+    mediaType: TrackType;
+    filePath: string;
+    intrinsicDuration: TimelineFrame;
+    nativeFps: FrameRate;
+    sourceTimecodeOffset: TimelineFrame;
+    status?: AssetStatus;
+}): FileAsset;
+
+/**
+ * EASING CURVES — Phase 4
+ *
+ * Discriminated union for keyframe/interpolation easing.
+ */
+type EasingCurve = {
+    readonly kind: 'Linear';
+} | {
+    readonly kind: 'Hold';
+} | {
+    readonly kind: 'EaseIn';
+    readonly power: number;
+} | {
+    readonly kind: 'EaseOut';
+    readonly power: number;
+} | {
+    readonly kind: 'EaseBoth';
+    readonly power: number;
+} | {
+    readonly kind: 'BezierCurve';
+    readonly p1x: number;
+    readonly p1y: number;
+    readonly p2x: number;
+    readonly p2y: number;
+};
+declare const LINEAR_EASING: EasingCurve;
+declare const HOLD_EASING: EasingCurve;
+
+/**
+ * KEYFRAME MODEL — Phase 4
+ *
+ * Single keyframe for animatable values (effect params, transform, audio).
+ */
+
+type KeyframeId = string & {
+    readonly __brand: 'KeyframeId';
+};
+declare function toKeyframeId(s: string): KeyframeId;
+/** Value is a plain number (opacity, scale, rotation, gain, etc.). */
+type Keyframe = {
+    readonly id: KeyframeId;
+    readonly frame: TimelineFrame;
+    readonly value: number;
+    /** Easing out of this keyframe. */
+    readonly easing: EasingCurve;
+};
+
+/**
+ * EFFECT MODEL — Phase 4
+ *
+ * Effect applied to a clip (blur, LUT, color correct, host-defined).
+ */
+
+type EffectId = string & {
+    readonly __brand: 'EffectId';
+};
+declare function toEffectId(s: string): EffectId;
+/** Open string: 'blur', 'lut', 'colorCorrect', host-defined. */
+type EffectType = string;
+type RenderStage = 'preComposite' | 'postComposite' | 'output';
+type EffectParam = {
+    readonly key: string;
+    readonly value: number | string | boolean;
+};
+type Effect = {
+    readonly id: EffectId;
+    readonly effectType: EffectType;
+    readonly enabled: boolean;
+    readonly renderStage: RenderStage;
+    readonly params: readonly EffectParam[];
+    readonly keyframes: readonly Keyframe[];
+};
+declare function createEffect(id: EffectId, effectType: EffectType, renderStage?: RenderStage, params?: readonly EffectParam[]): Effect;
+
+/**
+ * CLIP TRANSFORM — Phase 4
+ *
+ * Animatable position, scale, rotation, opacity, anchor.
+ * Each property: base value + optional keyframes.
+ */
+
+type AnimatableProperty = {
+    readonly value: number;
+    readonly keyframes: readonly Keyframe[];
+};
+declare function createAnimatableProperty(value: number): AnimatableProperty;
+type ClipTransform = {
+    readonly positionX: AnimatableProperty;
+    readonly positionY: AnimatableProperty;
+    readonly scaleX: AnimatableProperty;
+    readonly scaleY: AnimatableProperty;
+    readonly rotation: AnimatableProperty;
+    readonly opacity: AnimatableProperty;
+    readonly anchorX: AnimatableProperty;
+    readonly anchorY: AnimatableProperty;
+};
+declare const DEFAULT_CLIP_TRANSFORM: ClipTransform;
+
+/**
+ * AUDIO PROPERTIES — Phase 4
+ *
+ * Per-clip audio: gain, pan, mute, channel routing.
+ */
+
+type ChannelRouting = 'stereo' | 'mono' | 'left' | 'right';
+type AudioProperties = {
+    readonly gain: AnimatableProperty;
+    readonly pan: AnimatableProperty;
+    readonly mute: boolean;
+    readonly channelRouting: ChannelRouting;
+    readonly normalizationGain: number;
+};
+declare const DEFAULT_AUDIO_PROPERTIES: AudioProperties;
+
+/**
+ * TRANSITION MODEL — Phase 4
+ *
+ * Outgoing transition between clips (dissolve, wipe, etc.).
+ */
+
+type TransitionId = string & {
+    readonly __brand: 'TransitionId';
+};
+declare function toTransitionId(s: string): TransitionId;
+/** 'dissolve' | 'wipe' | 'dip' | host-defined. */
+type TransitionType = string;
+type TransitionAlignment = 'centerOnCut' | 'endAtCut' | 'startAtCut';
+type TransitionParam = {
+    readonly key: string;
+    readonly value: number | string | boolean;
+};
+type Transition = {
+    readonly id: TransitionId;
+    readonly type: TransitionType;
+    readonly durationFrames: number;
+    readonly alignment: TransitionAlignment;
+    readonly easing: EasingCurve;
+    readonly params: readonly TransitionParam[];
+};
+declare function createTransition(id: TransitionId, type: TransitionType, durationFrames: number, alignment?: TransitionAlignment, easing?: EasingCurve, params?: readonly TransitionParam[]): Transition;
+
+/**
+ * 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';
+};
+declare const toClipId: (s: string) => 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>;
+    readonly effects?: readonly Effect[];
+    readonly transform?: ClipTransform;
+    readonly audio?: AudioProperties;
+    readonly transition?: Transition;
+};
+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>;
+    effects?: readonly Effect[];
+    transform?: ClipTransform;
+    audio?: AudioProperties;
+    transition?: Transition;
+}): 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;
+
+/**
+ * CAPTION MODEL — Phase 3
+ *
+ * Captions live on Track.captions[]. Used for SRT/VTT and burn-in.
+ */
+
+type CaptionId = string & {
+    readonly __brand: 'CaptionId';
+};
+type CaptionStyle = {
+    readonly fontFamily: string;
+    readonly fontSize: number;
+    readonly color: string;
+    readonly backgroundColor: string;
+    readonly hAlign: 'left' | 'center' | 'right';
+    readonly vAlign: 'top' | 'center' | 'bottom';
+};
+type Caption = {
+    readonly id: CaptionId;
+    readonly text: string;
+    readonly startFrame: TimelineFrame;
+    readonly endFrame: TimelineFrame;
+    readonly language: string;
+    readonly style: CaptionStyle;
+    readonly burnIn: boolean;
+};
+
+/**
+ * TRACK GROUP — Phase 4
+ *
+ * Logical grouping of tracks (e.g. for nesting or UI collapse).
+ */
+
+type TrackGroupId = string & {
+    readonly __brand: 'TrackGroupId';
+};
+declare function toTrackGroupId(s: string): TrackGroupId;
+type TrackGroup = {
+    readonly id: TrackGroupId;
+    readonly label: string;
+    readonly trackIds: readonly TrackId[];
+    readonly collapsed: boolean;
+};
+declare function createTrackGroup(id: TrackGroupId, label: string, trackIds?: readonly TrackId[]): TrackGroup;
+
+/**
+ * TRACK MODEL — Phase 0 + Phase 3
+ *
+ * A Track is a horizontal container for Clips, always sorted by timelineStart.
+ * Phase 3: captions[] for subtitle/caption items.
+ */
+
+type TrackId = string & {
+    readonly __brand: 'TrackId';
+};
+declare const toTrackId: (s: string) => 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[];
+    /** Phase 3: captions on this track (e.g. subtitle/title). */
+    readonly captions: readonly Caption[];
+    readonly blendMode?: string;
+    readonly opacity?: number;
+    readonly groupId?: TrackGroupId;
+};
+declare function createTrack(params: {
+    id: string;
+    name: string;
+    type: TrackType;
+    clips?: readonly Clip[];
+    captions?: readonly Caption[];
+    locked?: boolean;
+    muted?: boolean;
+    solo?: boolean;
+    height?: number;
+    blendMode?: string;
+    opacity?: number;
+    groupId?: TrackGroupId;
+}): Track;
+/** Returns a new track with clips sorted ascending by timelineStart. */
+declare function sortTrackClips(track: Track): Track;
+
+/**
+ * MARKER TYPES — Phase 3
+ *
+ * Discriminated union: point (single frame) or range (frameStart..frameEnd).
+ * Markers live on Timeline.markers[]. linkedClipId moves with clip on ripple.
+ */
+
+type MarkerId = string & {
+    readonly __brand: 'MarkerId';
+};
+type MarkerScope = 'global' | 'personal' | 'export';
+type Marker = {
+    readonly type: 'point';
+    readonly id: MarkerId;
+    readonly frame: TimelineFrame;
+    readonly label: string;
+    readonly color: string;
+    readonly scope: MarkerScope;
+    readonly linkedClipId: ClipId | null;
+    readonly clipId?: ClipId;
+} | {
+    readonly type: 'range';
+    readonly id: MarkerId;
+    readonly frameStart: TimelineFrame;
+    readonly frameEnd: TimelineFrame;
+    readonly label: string;
+    readonly color: string;
+    readonly scope: MarkerScope;
+    readonly linkedClipId: ClipId | null;
+    readonly clipId?: ClipId;
+};
+type BeatGrid = {
+    readonly bpm: number;
+    readonly timeSignature: readonly [number, number];
+    readonly offset: TimelineFrame;
+};
+
+/**
+ * LINK GROUP — Phase 4
+ *
+ * Locks A/V clips in sync; when one moves, all move together.
+ */
+
+type LinkGroupId = string & {
+    readonly __brand: 'LinkGroupId';
+};
+declare function toLinkGroupId(s: string): LinkGroupId;
+type LinkGroup = {
+    readonly id: LinkGroupId;
+    /** Min 2 clips. */
+    readonly clipIds: readonly ClipId[];
+};
+declare function createLinkGroup(id: LinkGroupId, clipIds: readonly ClipId[]): LinkGroup;
+
+/**
+ * TIMELINE MODEL — Phase 0 + Phase 3
+ */
+
+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;
+    readonly markers: readonly Marker[];
+    readonly beatGrid: BeatGrid | null;
+    readonly inPoint: TimelineFrame | null;
+    readonly outPoint: TimelineFrame | null;
+    readonly trackGroups?: readonly TrackGroup[];
+    readonly linkGroups?: readonly LinkGroup[];
+};
+declare function createTimeline(params: {
+    id: string;
+    name: string;
+    fps: FrameRate;
+    duration: TimelineFrame;
+    startTimecode?: Timecode;
+    tracks?: readonly Track[];
+    sequenceSettings?: Partial<SequenceSettings>;
+    markers?: readonly Marker[];
+    beatGrid?: BeatGrid | null;
+    inPoint?: TimelineFrame | null;
+    outPoint?: TimelineFrame | null;
+    trackGroups?: readonly TrackGroup[];
+    linkGroups?: readonly LinkGroup[];
+}): 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>;
+/**
+ * Increment this whenever TimelineState gains a new required field or
+ * a field's semantics change in a breaking way.
+ *
+ * The schemaVersion invariant check rejects loading a future schema
+ * into an older engine (prevents silent data corruption on downgrade).
+ */
+declare const CURRENT_SCHEMA_VERSION: 2;
+type TimelineState = {
+    readonly schemaVersion: number;
+    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>;
+} | {
+    type: 'ADD_MARKER';
+    marker: Marker;
+} | {
+    type: 'MOVE_MARKER';
+    markerId: MarkerId;
+    newFrame: TimelineFrame;
+} | {
+    type: 'DELETE_MARKER';
+    markerId: MarkerId;
+} | {
+    type: 'SET_IN_POINT';
+    frame: TimelineFrame | null;
+} | {
+    type: 'SET_OUT_POINT';
+    frame: TimelineFrame | null;
+} | {
+    type: 'ADD_BEAT_GRID';
+    beatGrid: BeatGrid;
+} | {
+    type: 'REMOVE_BEAT_GRID';
+} | {
+    type: 'INSERT_GENERATOR';
+    generator: Generator;
+    trackId: TrackId;
+    atFrame: TimelineFrame;
+} | {
+    type: 'ADD_CAPTION';
+    caption: Omit<Caption, 'style'> & {
+        style?: CaptionStyle;
+    };
+    trackId: TrackId;
+} | {
+    type: 'EDIT_CAPTION';
+    captionId: CaptionId;
+    trackId: TrackId;
+    text?: string;
+    language?: string;
+    style?: Partial<CaptionStyle>;
+    burnIn?: boolean;
+    startFrame?: TimelineFrame;
+    endFrame?: TimelineFrame;
+} | {
+    type: 'DELETE_CAPTION';
+    captionId: CaptionId;
+    trackId: TrackId;
+} | {
+    type: 'ADD_EFFECT';
+    clipId: ClipId;
+    effect: Effect;
+} | {
+    type: 'REMOVE_EFFECT';
+    clipId: ClipId;
+    effectId: EffectId;
+} | {
+    type: 'REORDER_EFFECT';
+    clipId: ClipId;
+    effectId: EffectId;
+    newIndex: number;
+} | {
+    type: 'SET_EFFECT_ENABLED';
+    clipId: ClipId;
+    effectId: EffectId;
+    enabled: boolean;
+} | {
+    type: 'SET_EFFECT_PARAM';
+    clipId: ClipId;
+    effectId: EffectId;
+    key: string;
+    value: number | string | boolean;
+} | {
+    type: 'ADD_KEYFRAME';
+    clipId: ClipId;
+    effectId: EffectId;
+    keyframe: Keyframe;
+} | {
+    type: 'MOVE_KEYFRAME';
+    clipId: ClipId;
+    effectId: EffectId;
+    keyframeId: KeyframeId;
+    newFrame: TimelineFrame;
+} | {
+    type: 'DELETE_KEYFRAME';
+    clipId: ClipId;
+    effectId: EffectId;
+    keyframeId: KeyframeId;
+} | {
+    type: 'SET_KEYFRAME_EASING';
+    clipId: ClipId;
+    effectId: EffectId;
+    keyframeId: KeyframeId;
+    easing: EasingCurve;
+} | {
+    type: 'SET_CLIP_TRANSFORM';
+    clipId: ClipId;
+    transform: Partial<ClipTransform>;
+} | {
+    type: 'SET_AUDIO_PROPERTIES';
+    clipId: ClipId;
+    properties: Partial<AudioProperties>;
+} | {
+    type: 'ADD_TRANSITION';
+    clipId: ClipId;
+    transition: Transition;
+} | {
+    type: 'DELETE_TRANSITION';
+    clipId: ClipId;
+} | {
+    type: 'SET_TRANSITION_DURATION';
+    clipId: ClipId;
+    durationFrames: number;
+} | {
+    type: 'SET_TRANSITION_ALIGNMENT';
+    clipId: ClipId;
+    alignment: TransitionAlignment;
+} | {
+    type: 'LINK_CLIPS';
+    linkGroup: LinkGroup;
+} | {
+    type: 'UNLINK_CLIPS';
+    linkGroupId: LinkGroupId;
+} | {
+    type: 'ADD_TRACK_GROUP';
+    trackGroup: TrackGroup;
+} | {
+    type: 'DELETE_TRACK_GROUP';
+    trackGroupId: TrackGroupId;
+} | {
+    type: 'SET_TRACK_BLEND_MODE';
+    trackId: TrackId;
+    blendMode: string;
+} | {
+    type: 'SET_TRACK_OPACITY';
+    trackId: TrackId;
+    opacity: number;
+};
+/**
+ * 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' | 'NOT_FOUND' | 'BEAT_GRID_EXISTS' | 'CLIP_NOT_FOUND' | 'DUPLICATE_EFFECT_ID' | 'EFFECT_NOT_FOUND' | 'EFFECT_INDEX_OUT_OF_RANGE' | 'KEYFRAME_NOT_FOUND' | 'DUPLICATE_KEYFRAME_ID' | 'INVALID_RANGE' | 'TRANSITION_NOT_FOUND' | 'LINK_GROUP_NOT_FOUND' | 'TRACK_GROUP_NOT_FOUND' | 'DUPLICATE_LINK_GROUP_ID' | 'DUPLICATE_TRACK_GROUP_ID' | 'INVALID_OPACITY' | 'TRACK_NOT_FOUND';
+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' | 'SCHEMA_VERSION_MISMATCH' | 'MARKER_OUT_OF_BOUNDS' | 'IN_OUT_INVALID' | 'BEAT_GRID_INVALID' | 'CAPTION_OUT_OF_BOUNDS' | 'CAPTION_OVERLAP' | 'EFFECT_NOT_FOUND' | 'KEYFRAME_NOT_FOUND' | 'KEYFRAME_ORDER_VIOLATION' | 'EFFECT_INDEX_OUT_OF_RANGE' | 'INVALID_RENDER_STAGE' | 'TRACK_GROUP_NOT_FOUND' | 'INVALID_OPACITY' | 'INVALID_RANGE' | 'LINK_GROUP_NOT_FOUND';
+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;
+    readonly ctrlKey: boolean;
+    /** True when key is held and OS is firing repeated keydowns. */
+    readonly repeat?: boolean;
+};
+/** Pixel + frame region swept by a rubber-band (marquee) selection drag.
+ *  Populated by SelectionTool during rubber-band drags. */
+type RubberBandRegion = {
+    readonly startFrame: TimelineFrame;
+    readonly endFrame: TimelineFrame;
+    readonly startY: number;
+    readonly endY: number;
+};
+/** 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 rubberBand?: RubberBandRegion;
+    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;
+
+/**
+ * MARKER SEARCH API — Phase 3 Step 2
+ *
+ * Pure functions. Search state.timeline.markers only.
+ */
+
+/**
+ * Returns markers whose color exactly matches the given string.
+ */
+declare function findMarkersByColor(state: TimelineState, color: string): Marker[];
+/**
+ * Returns markers whose label contains the given string (case-insensitive).
+ */
+declare function findMarkersByLabel(state: TimelineState, label: string): Marker[];
+
+/**
+ * SUBTITLE IMPORT — Phase 3 Step 3
+ *
+ * Pure functions for parsing SRT/VTT into Caption[].
+ * No file IO. No DOM. No external deps.
+ */
+
+declare const defaultCaptionStyle: CaptionStyle;
+type SRTParseOptions = {
+    language?: string;
+    burnIn?: boolean;
+    defaultStyle?: Partial<CaptionStyle>;
+};
+type VTTParseOptions = SRTParseOptions;
+declare function parseSRT(raw: string, fps: number, options?: SRTParseOptions): Caption[];
+declare function parseVTT(raw: string, fps: number, options?: VTTParseOptions): Caption[];
+declare function subtitleImportToOps(captions: Caption[], trackId: TrackId): OperationPrimitive[];
+
+/**
+ * TransitionTool — Phase 4 Step 4
+ *
+ * Drag from a clip's right edge to create or resize a transition.
+ * Click on an existing transition area to delete it.
+ *
+ * RULES:
+ *   - onPointerMove never dispatches; returns ProvisionalState for preview
+ *   - onPointerUp never mutates instance state (capture-before-reset)
+ *   - Every instance variable reset in onCancel()
+ */
+
+declare class TransitionTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private pendingClipId;
+    private dragStartX;
+    private pendingDeleteTransitionClipId;
+    getCursor(_ctx: ToolContext): string;
+    getSnapCandidateTypes(): readonly SnapPointType[];
+    onPointerDown(event: TimelinePointerEvent, ctx: ToolContext): void;
+    onPointerMove(event: TimelinePointerEvent, ctx: ToolContext): ProvisionalState | null;
+    onPointerUp(event: TimelinePointerEvent, ctx: ToolContext): Transaction | null;
+    onKeyDown(_event: TimelineKeyEvent, _ctx: ToolContext): Transaction | null;
+    onKeyUp(_event: TimelineKeyEvent, _ctx: ToolContext): void;
+    onCancel(): void;
+}
+
+/**
+ * KeyframeTool (Pen tool) — Phase 4 Step 4
+ *
+ * Click on a clip's effect lane to add a keyframe.
+ * Click an existing keyframe to delete (via Delete key). Drag keyframe to move.
+ *
+ * RULES:
+ *   - onPointerMove never dispatches; returns ProvisionalState for preview
+ *   - onPointerUp never mutates instance state (capture-before-reset)
+ *   - Every instance variable reset in onCancel()
+ */
+
+declare class KeyframeTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private draggingKeyframe;
+    private activeClipId;
+    private activeEffectId;
+    private pendingAddKeyframe;
+    getCursor(_ctx: ToolContext): string;
+    getSnapCandidateTypes(): readonly SnapPointType[];
+    onPointerDown(event: TimelinePointerEvent, ctx: ToolContext): void;
+    onPointerMove(event: TimelinePointerEvent, ctx: ToolContext): ProvisionalState | null;
+    onPointerUp(event: TimelinePointerEvent, ctx: ToolContext): Transaction | null;
+    onKeyDown(event: TimelineKeyEvent, ctx: ToolContext): Transaction | null;
+    onKeyUp(_event: TimelineKeyEvent, _ctx: ToolContext): void;
+    onCancel(): void;
+}
+
+/**
+ * SerializationError — Phase 5 Step 1
+ *
+ * Thrown when deserialization or migration fails.
+ */
+
+declare class SerializationError extends Error {
+    readonly violations?: InvariantViolation[] | undefined;
+    constructor(message: string, violations?: InvariantViolation[] | undefined);
+}
+
+/**
+ * Timeline serialization — Phase 5 Step 1
+ *
+ * Pure functions. No IO. No DOM. No external deps.
+ * serializeTimeline / deserializeTimeline round-trip TimelineState.
+ */
+
+/**
+ * Serialize state to JSON string.
+ * Converts assetRegistry Map to plain object for JSON compatibility.
+ */
+declare function serializeTimeline(state: TimelineState): string;
+/**
+ * Parse JSON string, migrate to current schema, validate invariants.
+ * Throws SerializationError on invalid JSON, missing schemaVersion,
+ * unknown version, or invariant violations.
+ */
+declare function deserializeTimeline(raw: string): TimelineState;
+type AssetRemapCallback = (asset: FileAsset) => FileAsset;
+/**
+ * Walk assetRegistry; for each FileAsset replace with remap(asset).
+ * GeneratorAssets unchanged. Returns new state (immutable).
+ */
+declare function remapAssetPaths(state: TimelineState, remap: AssetRemapCallback): TimelineState;
+type OfflineAsset = {
+    readonly assetId: AssetId;
+    readonly path: string;
+    readonly clipIds: readonly ClipId[];
+};
+/**
+ * For each FileAsset where isOnline(asset) === false, collect clip IDs
+ * that reference it. Host provides isOnline; core does not do filesystem checks.
+ */
+declare function findOfflineAssets(state: TimelineState, isOnline: (asset: FileAsset) => boolean): OfflineAsset[];
+
+/**
+ * OTIO export — Phase 5 Step 2
+ *
+ * Pure function. Produces OTIO JSON-serializable document from TimelineState.
+ * No external OTIO library. Hand-rolled mapping.
+ */
+
+type OTIORationalTime = {
+    value: number;
+    rate: number;
+};
+type OTIOTimeRange = {
+    OTIO_SCHEMA: string;
+    start_time: OTIORationalTime;
+    duration: OTIORationalTime;
+};
+type OTIOExternalReference = {
+    OTIO_SCHEMA: string;
+    target_url: string;
+    available_range: OTIOTimeRange;
+};
+type OTIOGeneratorReference = {
+    OTIO_SCHEMA: string;
+    generator_kind: string;
+};
+type OTIOMissingReference = {
+    OTIO_SCHEMA: string;
+};
+type OTIOClip = {
+    OTIO_SCHEMA: string;
+    name: string;
+    source_range: OTIOTimeRange;
+    media_reference: OTIOExternalReference | OTIOGeneratorReference | OTIOMissingReference;
+    effects?: OTIOEffect[];
+};
+type OTIOGap = {
+    OTIO_SCHEMA: string;
+    source_range: OTIOTimeRange;
+};
+type OTIOEffect = {
+    OTIO_SCHEMA: string;
+    name: string;
+    effect_name: string;
+    enabled: boolean;
+    metadata: {
+        params: readonly {
+            key: string;
+            value: number | string | boolean;
+        }[];
+    };
+};
+type OTIOTrack = {
+    OTIO_SCHEMA: string;
+    kind: string;
+    children: (OTIOClip | OTIOGap)[];
+};
+type OTIOStack = {
+    OTIO_SCHEMA: string;
+    children: OTIOTrack[];
+};
+type OTIOMarker = {
+    OTIO_SCHEMA: string;
+    name: string;
+    color: string;
+    marked_range: OTIOTimeRange;
+};
+type OTIODocument = {
+    OTIO_SCHEMA: string;
+    name: string;
+    global_start_time: OTIORationalTime;
+    tracks: OTIOStack;
+    markers: OTIOMarker[];
+};
+/**
+ * Export TimelineState to an OTIO document (plain object).
+ * Caller can JSON.stringify the result.
+ */
+declare function exportToOTIO(state: TimelineState): OTIODocument;
+
+/**
+ * OTIO import — Phase 5 Step 2
+ *
+ * Pure function. Builds TimelineState from OTIO document.
+ * Throws SerializationError on invalid doc or invariant violations.
+ */
+
+type OTIOImportOptions = {
+    /** Override fps; default: from doc global_start_time.rate or first clip rate, fallback 30 */
+    fps?: number;
+    /** Override timeline name */
+    name?: string;
+};
+declare function importFromOTIO(doc: unknown, options?: OTIOImportOptions): TimelineState;
+
+/**
+ * CMX3600 EDL export — Phase 5 Step 3
+ *
+ * Single video track only. Pure function, returns string.
+ * No IO.
+ */
+
+type EDLExportOptions = {
+    /** Default: state.timeline.name */
+    title?: string;
+    /** Default: false (non-drop). True = 29.97 drop frame only. */
+    dropFrame?: boolean;
+    /** Which video track to export. Default: 0 (first video track). */
+    trackIndex?: number;
+};
+/**
+ * Convert frame count to timecode string.
+ * dropFrame true: only 29.97fps uses real drop-frame; others fall back to non-drop.
+ */
+declare function frameToTimecode(frame: number, fps: number, dropFrame: boolean): string;
+/**
+ * FileAsset: filename without extension, truncate 8 chars, uppercase.
+ * GeneratorAsset or undefined: "AX".
+ */
+declare function reelName(asset: Asset | undefined): string;
+/**
+ * Export a single video track to CMX3600 EDL string.
+ * trackIndex selects which video track (default 0).
+ */
+declare function exportToEDL(state: TimelineState, options?: EDLExportOptions): string;
+
+/**
+ * AAF XML export — Phase 5 Step 4
+ *
+ * Simplified AAF XML representation for Avid interchange.
+ * Pure function, returns string. No IO.
+ */
+
+type AAFExportOptions = {
+    /** Default: timeline name */
+    projectName?: string;
+    /** Default: derived from state (e.g. 30 → "30/1") */
+    frameRate?: string;
+};
+declare function exportToAAF(state: TimelineState, options?: AAFExportOptions): string;
+
+/**
+ * FCP XML (FCPX) export — Phase 5 Step 4
+ *
+ * Final Cut Pro XML 1.10 interchange. Pure function, returns string. No IO.
+ */
+
+type FCPXMLExportOptions = {
+    libraryName?: string;
+    eventName?: string;
+};
+/**
+ * FCPXML rational time: "0s" or "{frames}/{fps}s".
+ */
+declare function toFCPTime(frames: number, fps: number): string;
+declare function exportToFCPXML(state: TimelineState, options?: FCPXMLExportOptions): string;
+
+/**
+ * PROJECT MODEL — Phase 5 Step 5
+ *
+ * A Project is a multi-timeline container with a shared bin hierarchy.
+ * Pure types + factories only. No IO.
+ */
+
+type ProjectId = string & {
+    readonly __brand: 'ProjectId';
+};
+declare function toProjectId(s: string): ProjectId;
+type BinId = string & {
+    readonly __brand: 'BinId';
+};
+declare function toBinId(s: string): BinId;
+type BinItem = {
+    readonly kind: 'asset';
+    readonly assetId: AssetId;
+} | {
+    readonly kind: 'sequence';
+    readonly timelineId: string;
+} | {
+    readonly kind: 'bin';
+    readonly binId: BinId;
+};
+type Bin = {
+    readonly id: BinId;
+    readonly label: string;
+    readonly parentId: BinId | null;
+    readonly items: readonly BinItem[];
+    readonly color?: string;
+};
+declare function createBin(id: BinId, label: string, parentId?: BinId | null): Bin;
+type Project = {
+    readonly id: ProjectId;
+    readonly name: string;
+    readonly timelines: readonly TimelineState[];
+    readonly bins: readonly Bin[];
+    readonly rootBinIds: readonly BinId[];
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly schemaVersion: number;
+};
+declare function createProject(id: ProjectId, name: string, timelines?: readonly TimelineState[]): Project;
+
+declare function addTimeline(project: Project, state: TimelineState): Project;
+declare function removeTimeline(project: Project, timelineId: string): Project;
+declare function addBin(project: Project, bin: Bin): Project;
+declare function removeBin(project: Project, binId: BinId): Project;
+declare function addItemToBin(project: Project, binId: BinId, item: BinItem): Project;
+declare function removeItemFromBin(project: Project, binId: BinId, item: BinItem): Project;
+declare function moveItemBetweenBins(project: Project, fromBinId: BinId, toBinId: BinId, item: BinItem): Project;
+
+/**
+ * Project serialization — Phase 5 Step 5
+ *
+ * Pure functions. No IO. Uses timeline migrate() + checkInvariants().
+ */
+
+declare function serializeProject(project: Project): string;
+declare function deserializeProject(raw: string): Project;
+
+/**
+ * Playhead types — Phase 6 Step 1 + Step 5
+ *
+ * Playback position and quality. No DOM deps.
+ */
+
+type PlaybackRate = number;
+type PlaybackQuality = 'full' | 'half' | 'quarter' | 'proxy';
+type LoopRegion = {
+    readonly startFrame: TimelineFrame;
+    readonly endFrame: TimelineFrame;
+};
+type PlayheadState = {
+    readonly currentFrame: TimelineFrame;
+    readonly isPlaying: boolean;
+    readonly playbackRate: PlaybackRate;
+    readonly quality: PlaybackQuality;
+    readonly durationFrames: number;
+    readonly fps: number;
+    readonly loopRegion: LoopRegion | null;
+    readonly prerollFrames: number;
+    readonly postrollFrames: number;
+};
+type PlayheadEventType = 'play' | 'pause' | 'seek' | 'loop' | 'frame-dropped' | 'ended' | 'loop-point';
+type PlayheadEvent = {
+    readonly type: PlayheadEventType;
+    readonly frame: TimelineFrame;
+    readonly data?: unknown;
+};
+type PlayheadListener = (event: PlayheadEvent) => void;
+/** Return type of PlayheadController.on() — call to unsubscribe. */
+type PlayheadUnsubscribe = () => void;
+
+/**
+ * Clock abstraction — Phase 6 Step 1
+ *
+ * Allows PlayheadController to run without real rAF (swapped for mock in tests).
+ */
+type ClockCallback = (timestamp: number) => void;
+type Clock = {
+    requestFrame: (cb: ClockCallback) => number;
+    cancelFrame: (id: number) => void;
+    now: () => number;
+};
+declare const browserClock: Clock;
+declare const nodeClock: Clock;
+declare function createTestClock(): {
+    clock: Clock;
+    tick: (ms: number) => void;
+    getCallbacks: () => ClockCallback[];
+};
+
+/**
+ * PlayheadController — Phase 6 Step 1
+ *
+ * Manages playback position only. Decoupled from Dispatcher and TimelineState.
+ * Never calls dispatch(). Uses clock abstraction for testability.
+ */
+
+declare class PlayheadController {
+    private state;
+    private listeners;
+    private rafId;
+    private lastTimestamp;
+    private frameAccum;
+    private clock;
+    constructor(initialState: Pick<PlayheadState, 'durationFrames' | 'fps'>, clock?: Clock);
+    getState(): PlayheadState;
+    play(): void;
+    pause(): void;
+    seekTo(frame: TimelineFrame): void;
+    setPlaybackRate(rate: PlaybackRate): void;
+    setQuality(quality: PlaybackQuality): void;
+    setDuration(durationFrames: number): void;
+    setLoopRegion(region: LoopRegion | null): void;
+    setPreroll(frames: number): void;
+    setPostroll(frames: number): void;
+    private scheduleFrame;
+    private onFrame;
+    on(listener: PlayheadListener): PlayheadUnsubscribe;
+    private emit;
+    destroy(): void;
+}
+
+/**
+ * Pipeline contracts — Phase 6 Step 2
+ *
+ * Core defines the CONTRACT (types + interfaces).
+ * Host app provides the IMPLEMENTATION.
+ * Core never does actual decoding or compositing.
+ */
+
+type VideoFrameRequest = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly quality: PlaybackQuality;
+};
+type AudioChunkRequest = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly durationFrames: number;
+    readonly sampleRate: number;
+};
+type VideoFrameResult = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly width: number;
+    readonly height: number;
+    readonly bitmap: unknown;
+};
+type AudioChunkResult = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly samples: unknown;
+    readonly sampleRate: number;
+};
+type VideoDecoder = (request: VideoFrameRequest) => Promise<VideoFrameResult>;
+type AudioDecoder = (request: AudioChunkRequest) => Promise<AudioChunkResult>;
+type CompositeLayer = {
+    readonly clipId: ClipId;
+    readonly trackId: TrackId;
+    readonly trackIndex: number;
+    readonly frame: VideoFrameResult;
+    readonly transform: ClipTransform;
+    readonly opacity: number;
+    readonly blendMode: string;
+    readonly effects: readonly Effect[];
+};
+/** Layer spec from resolveFrame (no decoded frame yet). */
+type ResolvedLayer = {
+    readonly clipId: ClipId;
+    readonly trackId: TrackId;
+    readonly trackIndex: number;
+    readonly mediaFrame: TimelineFrame;
+    readonly transform: ClipTransform;
+    readonly opacity: number;
+    readonly blendMode: string;
+    readonly effects: readonly Effect[];
+};
+type CompositeRequest = {
+    readonly timelineFrame: TimelineFrame;
+    readonly layers: readonly CompositeLayer[];
+    readonly width: number;
+    readonly height: number;
+    readonly quality: PlaybackQuality;
+};
+type CompositeResult = {
+    readonly timelineFrame: TimelineFrame;
+    readonly bitmap: unknown;
+};
+/** Result of resolveFrame (layers have mediaFrame, not decoded frame). */
+type ResolvedCompositeRequest = {
+    readonly timelineFrame: TimelineFrame;
+    readonly layers: readonly ResolvedLayer[];
+    readonly width: number;
+    readonly height: number;
+    readonly quality: PlaybackQuality;
+};
+type Compositor = (request: CompositeRequest) => Promise<CompositeResult>;
+type ThumbnailRequest = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly width: number;
+    readonly height: number;
+};
+type ThumbnailResult = {
+    readonly clipId: ClipId;
+    readonly mediaFrame: TimelineFrame;
+    readonly bitmap: unknown;
+};
+type ThumbnailProvider = (request: ThumbnailRequest) => Promise<ThumbnailResult>;
+type PipelineConfig = {
+    readonly videoDecoder: VideoDecoder;
+    readonly audioDecoder?: AudioDecoder;
+    readonly compositor: Compositor;
+    readonly thumbnailProvider?: ThumbnailProvider;
+};
+
+/**
+ * Frame resolver — Phase 6 Step 2 + Step 3
+ *
+ * Given a TimelineFrame, resolves which clips are visible and builds
+ * the composite request. Pure function — no async, no decoding.
+ */
+
+/**
+ * Returns the media-space frame for a clip at the given timeline frame.
+ * mediaFrame = timelineFrame - clip.timelineStart + clip.mediaIn
+ */
+declare function mediaFrameForClip(clip: Clip, timelineFrame: TimelineFrame): TimelineFrame;
+/**
+ * Returns all clips visible at the given timeline frame, with their
+ * parent track and track index (z-order).
+ */
+declare function getClipsAtFrame(state: TimelineState, timelineFrame: TimelineFrame): Array<{
+    clip: Clip;
+    track: Track;
+    trackIndex: number;
+}>;
+/**
+ * Resolves the composite request for a timeline frame: which layers are
+ * visible and their transform/opacity/blend/effects. Does not decode.
+ */
+declare function resolveFrame(state: TimelineState, timelineFrame: TimelineFrame, quality: PlaybackQuality, dimensions: {
+    width: number;
+    height: number;
+}): ResolvedCompositeRequest;
+/**
+ * Returns the nearest frame strictly after fromFrame where any clip
+ * starts or ends on any track. Returns null if none.
+ */
+declare function findNextClipBoundary(state: TimelineState, fromFrame: TimelineFrame): TimelineFrame | null;
+/**
+ * Returns the nearest frame strictly before fromFrame where any clip
+ * starts or ends on any track. Returns null if none.
+ */
+declare function findPrevClipBoundary(state: TimelineState, fromFrame: TimelineFrame): TimelineFrame | null;
+/**
+ * Returns the marker with the smallest anchor strictly after fromFrame.
+ * Point markers use .frame; range markers use .frameStart as anchor.
+ */
+declare function findNextMarker(state: TimelineState, fromFrame: TimelineFrame): Marker | null;
+/**
+ * Returns the marker with the largest anchor strictly before fromFrame.
+ */
+declare function findPrevMarker(state: TimelineState, fromFrame: TimelineFrame): Marker | null;
+/**
+ * Searches all tracks for a clip with the given id.
+ * Returns clip + parent track + trackIndex, or null if not found.
+ */
+declare function findClipById(state: TimelineState, clipId: ClipId): {
+    clip: Clip;
+    track: Track;
+    trackIndex: number;
+} | null;
+
+declare class PlaybackEngine {
+    private controller;
+    private pipeline;
+    private state;
+    private dimensions;
+    private unsubscribe;
+    constructor(state: TimelineState, pipeline: PipelineConfig, dimensions: {
+        width: number;
+        height: number;
+    }, clock?: Clock);
+    updateState(state: TimelineState): void;
+    play(): void;
+    pause(): void;
+    seekTo(frame: TimelineFrame): void;
+    seekToNextClipBoundary(): void;
+    seekToPrevClipBoundary(): void;
+    seekToNextMarker(): void;
+    seekToPrevMarker(): void;
+    seekToStart(): void;
+    seekToEnd(): void;
+    setPlaybackRate(rate: PlaybackRate): void;
+    setQuality(quality: PlaybackQuality): void;
+    setLoopRegion(region: LoopRegion | null): void;
+    setPreroll(frames: number): void;
+    setPostroll(frames: number): void;
+    getState(): PlayheadState;
+    getCurrentTimelineState(): TimelineState;
+    on(listener: PlayheadListener): () => void;
+    renderFrame(timelineFrame: TimelineFrame): Promise<CompositeResult>;
+    destroy(): void;
+}
+
+/**
+ * Keyboard contract — Phase 6 Step 4 + Step 5
+ *
+ * Key bindings and actions for J/K/L jog-shuttle and timeline navigation.
+ */
+
+type TimelineKeyAction = 'play-pause' | 'stop' | 'jog-forward' | 'jog-backward' | 'jog-stop' | 'step-forward' | 'step-backward' | 'seek-start' | 'seek-end' | 'next-clip' | 'prev-clip' | 'next-marker' | 'prev-marker' | 'mark-in' | 'mark-out' | 'toggle-loop';
+type KeyBinding = {
+    readonly code: string;
+    readonly shift?: boolean;
+    readonly alt?: boolean;
+    readonly meta?: boolean;
+    readonly ctrl?: boolean;
+    readonly action: TimelineKeyAction;
+    readonly repeat?: boolean;
+};
+declare const DEFAULT_KEY_BINDINGS: KeyBinding[];
+type KeyboardHandlerOptions = {
+    bindings?: KeyBinding[];
+    onMarkIn?: (frame: TimelineFrame) => void;
+    onMarkOut?: (frame: TimelineFrame) => void;
+    getTimelineState?: () => TimelineState;
+};
+
+/**
+ * KeyboardHandler — Phase 6 Step 4
+ *
+ * J/K/L jog-shuttle and keyboard contract. Zero DOM deps;
+ * accepts TimelineKeyEvent (host maps from KeyboardEvent).
+ */
+
+declare class KeyboardHandler {
+    private bindings;
+    private engine;
+    private jogLevel;
+    private onMarkIn;
+    private onMarkOut;
+    private getTimelineState;
+    constructor(engine: PlaybackEngine, options?: KeyboardHandlerOptions);
+    handleKeyDown(event: TimelineKeyEvent): boolean;
+    private dispatchAction;
+}
+
+export { type LoopRegion as $, type Asset as A, type Bin as B, type Clip as C, DEFAULT_AUDIO_PROPERTIES as D, type EDLExportOptions as E, type EasingCurve as F, type Effect as G, type EffectId as H, type EffectParam as I, type EffectType as J, type FCPXMLExportOptions as K, type FrameRate as L, FrameRates as M, HOLD_EASING as N, type HistoryState as O, type ITool as P, type InvariantViolation as Q, type KeyBinding as R, KeyboardHandler as S, type TimelineState as T, type KeyboardHandlerOptions as U, type Keyframe as V, type KeyframeId as W, KeyframeTool as X, LINEAR_EASING as Y, type LinkGroup as Z, type LinkGroupId as _, type Track as a, addTimeline as a$, type Modifiers as a0, NoOpTool as a1, type OTIODocument as a2, type OTIOImportOptions as a3, type OfflineAsset as a4, type OperationPrimitive as a5, type PipelineConfig as a6, PlaybackEngine as a7, type PlaybackQuality as a8, type PlaybackRate as a9, TimelineEngine as aA, type TimelineKeyAction as aB, type TimelineKeyEvent as aC, type TimelinePointerEvent as aD, type ToolContext as aE, type ToolId as aF, type ToolRegistry as aG, type TrackGroup as aH, type TrackGroupId as aI, type TrackId as aJ, type TrackType as aK, type Transaction as aL, type Transition as aM, type TransitionAlignment as aN, type TransitionId as aO, type TransitionParam as aP, TransitionTool as aQ, type TransitionType as aR, type VTTParseOptions as aS, type VideoDecoder as aT, type VideoFrameRequest as aU, type VideoFrameResult as aV, type ViolationType as aW, activateTool as aX, addBin as aY, addFrames as aZ, addItemToBin as a_, PlayheadController as aa, type PlayheadEvent as ab, type PlayheadEventType as ac, type PlayheadListener as ad, type PlayheadState as ae, type PlayheadUnsubscribe as af, type Project as ag, type ProjectId as ah, type ProvisionalManager as ai, type ProvisionalState as aj, type RationalTime as ak, type RejectionReason as al, type RenderStage as am, type RubberBandRegion as an, type SRTParseOptions as ao, type SequenceSettings as ap, SerializationError as aq, type SnapIndex as ar, type SnapPoint as as, type SnapPointType as at, type ThumbnailProvider as au, type ThumbnailRequest as av, type ThumbnailResult as aw, type TimeRange as ax, type Timecode as ay, type Timeline as az, type TimelineFrame as b, registerTool as b$, browserClock as b0, buildSnapIndex as b1, canRedo as b2, canUndo as b3, checkInvariants as b4, clampFrame as b5, clearProvisional as b6, clipContainsFrame as b7, clipsOverlap as b8, createAnimatableProperty as b9, findNextMarker as bA, findOfflineAssets as bB, findPrevClipBoundary as bC, findPrevMarker as bD, frame as bE, frameDuration as bF, frameRate as bG, frameToTimecode as bH, framesToMinutesSeconds as bI, framesToSeconds as bJ, framesToTimecode as bK, getActiveTool as bL, getClipDuration as bM, getClipMediaDuration as bN, getCurrentState as bO, importFromOTIO as bP, isDropFrame as bQ, isValidFrame as bR, mediaFrameForClip as bS, moveItemBetweenBins as bT, nearest as bU, nodeClock as bV, parseSRT as bW, parseVTT as bX, pushHistory as bY, redo as bZ, reelName as b_, createAsset as ba, createBin as bb, createClip as bc, createEffect as bd, createHistory as be, createLinkGroup as bf, createProject as bg, createProvisionalManager as bh, createRegistry as bi, createTestClock as bj, createTimeline as bk, createTimelineState as bl, createTrack as bm, createTrackGroup as bn, createTransition as bo, defaultCaptionStyle as bp, deserializeProject as bq, deserializeTimeline as br, dispatch as bs, exportToAAF as bt, exportToEDL as bu, exportToFCPXML as bv, exportToOTIO as bw, findMarkersByColor as bx, findMarkersByLabel as by, findNextClipBoundary as bz, type AAFExportOptions as c, remapAssetPaths as c0, removeBin as c1, removeItemFromBin as c2, removeTimeline as c3, resolveClip as c4, resolveFrame as c5, secondsToFrames as c6, serializeProject as c7, serializeTimeline as c8, setProvisional as c9, sortTrackClips as ca, subtitleImportToOps as cb, subtractFrames as cc, toAssetId as cd, toBinId as ce, toClipId as cf, toEffectId as cg, toFCPTime as ch, toFrame as ci, toKeyframeId as cj, toLinkGroupId as ck, toProjectId as cl, toTimecode as cm, toToolId as cn, toTrackGroupId as co, toTrackId as cp, toTransitionId as cq, toggleSnap as cr, undo as cs, findClipById as ct, getClipsAtFrame as cu, type AnimatableProperty as d, type AssetId as e, type AssetRegistry as f, type AssetRemapCallback as g, type AssetStatus as h, type AudioChunkRequest as i, type AudioChunkResult as j, type AudioDecoder as k, type AudioProperties as l, type BinId as m, type BinItem as n, CURRENT_SCHEMA_VERSION as o, type ChannelRouting as p, type ClipId as q, type ClipTransform as r, type Clock as s, type CompositeLayer as t, type CompositeRequest as u, type CompositeResult as v, type Compositor as w, DEFAULT_CLIP_TRANSFORM as x, DEFAULT_KEY_BINDINGS as y, type DispatchResult as z };