@webpacked-timeline/core 1.0.0-beta.1

package/dist/index-BJv6hDHL.d.ts

@@ -0,0 +1,3255 @@
+/**
+ * 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[];
+
+/**
+ * Transaction compression policy — Phase 7 Step 3
+ *
+ * Rapid same-type ops within a time window can be merged
+ * into a single history entry (last-write-wins).
+ */
+type CompressionPolicy = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'last-write-wins';
+    readonly windowMs: number;
+};
+type CompressibleOpType = 'MOVE_CLIP' | 'SET_CLIP_TRANSFORM' | 'SET_AUDIO_PROPERTIES' | 'SET_EFFECT_PARAM' | 'MOVE_KEYFRAME' | 'SET_TRANSITION_DURATION' | 'MOVE_MARKER' | 'SET_IN_POINT' | 'SET_OUT_POINT' | 'SET_TRACK_OPACITY';
+declare const DEFAULT_COMPRESSION_POLICY: CompressionPolicy;
+declare const NO_COMPRESSION: CompressionPolicy;
+
+/**
+ * HISTORY ENGINE
+ *
+ * Snapshot-based undo/redo system for timeline state.
+ *
+ * Two APIs:
+ * - HistoryState + pure functions (createHistory, pushHistory, undo, redo)
+ * - HistoryStack class with compression, checkpoints, and persistence
+ */
+
+/**
+ * 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;
+type HistoryEntry = {
+    readonly state: TimelineState;
+    readonly transaction: Transaction;
+};
+declare class HistoryStack {
+    private entries;
+    private undoIndex;
+    private limit;
+    private compressor;
+    private clock;
+    private checkpoints;
+    constructor(limit?: number, policy?: CompressionPolicy, clock?: () => number);
+    push(entry: HistoryEntry): void;
+    pushWithCompression(entry: HistoryEntry, transaction: Transaction): void;
+    resetCompression(): void;
+    undo(): TimelineState | null;
+    redo(): TimelineState | null;
+    getCurrentState(): TimelineState | null;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    saveCheckpoint(name: string): void;
+    restoreCheckpoint(name: string): HistoryEntry | null;
+    listCheckpoints(): string[];
+    clearCheckpoint(name: string): void;
+    serialize(): string;
+    static deserialize(raw: string, limit?: number, policy?: CompressionPolicy, clock?: () => number): HistoryStack;
+    softLimitWarning(): boolean;
+}
+
+/**
+ * TransactionCompressor — Phase 7 Step 3
+ *
+ * Decides whether a transaction should be merged into the previous
+ * history entry (same op type within window).
+ */
+
+declare class TransactionCompressor {
+    private lastOpType;
+    private lastTime;
+    private policy;
+    private clock;
+    constructor(policy?: CompressionPolicy, clock?: () => number);
+    shouldCompress(transaction: Transaction, now: number): boolean;
+    record(transaction: Transaction, now: number): void;
+    reset(): void;
+}
+
+/**
+ * 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;
+
+/**
+ * SnapIndexManager — Phase 7 Step 2
+ *
+ * Debounces SnapIndex rebuilds using queueMicrotask.
+ * Multiple scheduleRebuild() calls in one turn → single rebuild.
+ */
+
+declare class SnapIndexManager {
+    private index;
+    private state;
+    private pending;
+    getIndex(): SnapIndex | null;
+    scheduleRebuild(state: TimelineState): void;
+    rebuildSync(state: TimelineState): void;
+    get isPending(): boolean;
+}
+
+/**
+ * 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[];
+
+/**
+ * SelectionTool — Phase 2
+ *
+ * The most complex tool. Handles four interaction modes:
+ *   MODE 1: Single click  → select/deselect clip (no drag)
+ *   MODE 2: Single drag   → move one clip, produce MOVE_CLIP Transaction
+ *   MODE 3: Multi drag    → move all selected clips by uniform delta, N× MOVE_CLIP
+ *   MODE 4: Rubber-band   → marquee select clips, no Transaction
+ *
+ * SELECTION CONTRACT:
+ *   Selection lives on this instance as Set<ClipId>.
+ *   It is NOT in TimelineState. It is NOT undoable.
+ *   onCancel() resets all instance state, including selection.
+ *
+ * GHOST CLIP CONTRACT (corrected in design review):
+ *   Ghost clips are ALWAYS built by reading the live clip from ctx.state
+ *   then overriding position fields. Never spread a stored clip snapshot.
+ *   originalPositions is ONLY used in onPointerUp for MOVE_CLIP delta math.
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove must never call dispatch
+ *   - onPointerUp must never mutate instance state
+ *   - Every instance variable appears in onCancel() — no exceptions
+ */
+
+declare class SelectionTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private readonly selected;
+    private mode;
+    private dragStartFrame;
+    private dragStartX;
+    private dragStartY;
+    private dragClipId;
+    private isMultiDrag;
+    /** Frame values only — no Clip objects. Used only in onPointerUp for delta math. */
+    private originalPositions;
+    private rubberBandStartFrame;
+    private rubberBandStartY;
+    private lastClientX;
+    private lastHitEdge;
+    getSelection(): ReadonlySet<ClipId>;
+    clearSelection(): void;
+    getCursor(_ctx: ToolContext): string;
+    private _lastHoveredClipId;
+    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;
+    /**
+     * Reset ALL instance state.
+     * Every instance variable must appear here.
+     * If a new variable is added to the class, it MUST be added here too.
+     */
+    onCancel(): void;
+    /** Reset per-gesture drag state WITHOUT clearing selection. */
+    private _resetDragState;
+}
+
+/**
+ * RazorTool — Phase 2 Step 2
+ *
+ * Click on a clip at any frame → split it into two clips at that frame.
+ * Shift+click (ctx.modifiers.shift) → split ALL clips at that frame across ALL tracks.
+ *
+ * CONTRACT:
+ *   - No drag, no provisional ghost, no rubber-band
+ *   - onPointerMove always returns null
+ *   - Every Transaction is DELETE_CLIP + INSERT_CLIP(left) + INSERT_CLIP(right), per clip
+ *   - New ClipIds are generated by generateId() — replaceable in tests via _setIdGenerator()
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - ctx.modifiers.shift is the authoritative source for shift detection (not event.shiftKey)
+ *   - Both halves need strictly positive duration — reject if atFrame is at clip boundary
+ */
+
+declare class RazorTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    /** Snapped slice frame captured at onPointerDown. */
+    private pendingFrame;
+    /** ClipId hit at onPointerDown. null if clicking empty space or for shift+all. */
+    private pendingClipId;
+    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;
+    /**
+     * Reset ALL instance state.
+     * Every instance variable must appear here.
+     */
+    onCancel(): void;
+    private _findClip;
+    /**
+     * Slice every clip that contains `atFrame` across all tracks.
+     * Groups operations per-clip: DELETE then INSERT left then INSERT right.
+     * Tracks where no clip spans `atFrame` contribute zero operations.
+     */
+    private _sliceAllTracks;
+}
+
+/**
+ * RippleTrimTool — Phase 2 Step 3
+ *
+ * Drag a clip edge (start or end). The dragged edge moves.
+ * All clips downstream of the edit point shift by the same delta.
+ *
+ * DOWNSTREAM DEFINITION:
+ *   END edge trim:   clips with timelineStart >= original.timelineEnd  (to the right)
+ *   START edge trim: clips with timelineEnd   <= original.timelineStart (to the left)
+ *
+ * START EDGE SEMANTICS:
+ *   When the start edge moves right (+delta), left clips also shift right (+delta).
+ *   When the start edge moves left  (-delta), left clips also shift left  (-delta).
+ *   This is standard NLE ripple trim behavior (Premiere / Resolve convention).
+ *
+ * TRANSACTION ORDER:
+ *   RESIZE_CLIP first, then N× MOVE_CLIP.
+ *   Rolling-state validation means MOVE_CLIPs validate after RESIZE is applied.
+ *
+ * CLAMPING (applied before ghost and Transaction):
+ *   1. Min duration: clip must remain ≥ 1 frame
+ *   2. Media bounds: mediaIn must stay < mediaOut - 1 (START); mediaOut > mediaIn + 1 (END)
+ *   3. Frame-0: for START trim, leftward shift must not push any left-clip below frame 0
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove never dispatches
+ *   - onPointerUp never mutates instance state
+ *   - Every instance variable appears in onCancel()
+ */
+
+declare class RippleTrimTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private dragClipId;
+    private dragEdge;
+    /** Original clip bounds — frame values only, never a stale Clip object. */
+    private dragOrigStart;
+    private dragOrigEnd;
+    private dragOrigMediaIn;
+    private dragOrigMediaOut;
+    /**
+     * Original positions of downstream clips.
+     * Keyed by ClipId. Both timelineStart and timelineEnd stored — ghost needs
+     * both to render, MOVE_CLIP only needs start (but duration is end - start).
+     */
+    private originalDownstream;
+    private lastHitEdge;
+    private lastHoveredClipId;
+    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;
+    /** Reset ALL instance state. Every variable must appear here. */
+    onCancel(): void;
+    /**
+     * Apply all clamping rules to the candidate newFrame.
+     * Returns null if the resulting trim would produce a zero-or-negative-duration clip.
+     */
+    private _clampFrame;
+    /**
+     * Build the ProvisionalState showing trimmed clip + all shifted downstream clips.
+     * Always reads live clip data from ctx.state — never spreads stored clip objects.
+     */
+    private _buildGhost;
+    /** Reset per-drag instance state. Does NOT touch getCursor vars. */
+    private _resetDragState;
+}
+
+/**
+ * RollTrimTool — Phase 2 Step 4
+ *
+ * Drag the boundary between two adjacent clips.
+ * Left clip's end and right clip's start move together to the same frame.
+ * Combined duration of both clips is unchanged.
+ * No downstream ripple. No upstream ripple.
+ *
+ * TRANSACTION: 2× RESIZE_CLIP with identical newFrame. One history entry.
+ *
+ * CLAMP (precomputed at onPointerDown — only 5 instance vars needed):
+ *   minBoundary = max(leftOrig.timelineStart + 1,
+ *                     origBoundary - (leftOrig.mediaOut - leftOrig.mediaIn - 1))
+ *   maxBoundary = min(rightOrig.timelineEnd - 1,
+ *                     origBoundary + (rightOrig.mediaOut - rightOrig.mediaIn - 1))
+ *
+ * ORIGBOUNDARY AT onPointerUp:
+ *   Read from ctx.state (committed, not yet changed) — avoids a 6th instance var.
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove never dispatches
+ *   - onPointerUp never mutates instance state
+ *   - Every instance variable appears in onCancel()
+ *   - Capture-before-reset pattern: compute clamp BEFORE _resetDragState()
+ */
+
+declare class RollTrimTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private leftClipId;
+    private rightClipId;
+    /**
+     * Precomputed clamp bounds — computed once at onPointerDown from all 4 constraints.
+     * Avoids storing all 8 original clip bounds as separate instance vars.
+     */
+    private minBoundary;
+    private maxBoundary;
+    /** True when the pointer is hovering a valid cut point (within EDGE_ZONE). */
+    private isHoveringCut;
+    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;
+    /** Reset ALL instance state. Every variable must appear here. */
+    onCancel(): void;
+    private _buildGhost;
+    private _resetDragState;
+}
+
+/**
+ * SlipTool — Phase 2 Step 5
+ *
+ * Drag a clip to shift its media window. The clip's timeline position is
+ * unchanged — only mediaIn and mediaOut move together by the same delta.
+ *
+ * OPERATION: Single SET_MEDIA_BOUNDS. No MOVE_CLIP. No RESIZE_CLIP. Nothing else.
+ *
+ * DELTA: rawDelta = event.frame - dragStartFrame (no snapping — slip is in media space)
+ *
+ * CLAMP:
+ *   minDelta = -clip.mediaIn                           → mediaIn + delta >= 0
+ *   maxDelta = asset.intrinsicDuration - clip.mediaOut → mediaOut + delta <= intrinsicDuration
+ *   clampedDelta = clamp(rawDelta, minDelta, maxDelta)
+ *
+ * SNAP: none. getSnapCandidateTypes returns [].
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove never dispatches
+ *   - onPointerUp never mutates instance state
+ *   - Every instance variable appears in onCancel()
+ *   - Capture-before-reset: compute delta BEFORE _resetDragState()
+ */
+
+declare class SlipTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    /** Clip being slipped. Null when idle. */
+    private dragClipId;
+    /** Frame at which pointer went down. Delta = currentFrame - dragStartFrame. */
+    private dragStartFrame;
+    /** Staged by onPointerMove — getCursor() has no event parameter. */
+    private isHoveringClip;
+    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;
+    /** Reset ALL instance state. Every variable must appear here. */
+    onCancel(): void;
+    private _resetDragState;
+}
+
+/**
+ * RippleDeleteTool — Phase 2 Step 6
+ *
+ * Click a clip to delete it. All clips to the right on the same track
+ * shift left by the deleted clip's duration. No drag. No provisional state.
+ *
+ * TRANSACTION:
+ *   DELETE_CLIP { clipId }
+ *   MOVE_CLIP×N — one per downstream clip, sorted LEFT-TO-RIGHT
+ *
+ * MOVE_CLIP ordering rule (OPERATIONS.md: delta is negative → left-to-right):
+ *   Leftmost clip moves first into space vacated by DELETE_CLIP.
+ *   Each subsequent clip moves into space vacated by the one before it.
+ *   Wrong order → OVERLAP rejection from rolling-state validator.
+ *
+ * ACTIVATION: RippleDeleteTool is activated programmatically (e.g. when Delete
+ * is pressed while a clip is selected in SelectionTool). shortcutKey is empty
+ * because 'delete' is not a single-char tool-activation key.
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove never dispatches (returns null always)
+ *   - onPointerUp never mutates instance state
+ *   - Every instance variable appears in onCancel()
+ *   - Capture-before-reset pattern applied in onPointerUp
+ */
+
+declare class RippleDeleteTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    /**
+     * Clip targeted at onPointerDown. Read and cleared at onPointerUp.
+     * No drag, no delta, no edge — this tool is click-only.
+     */
+    private pendingClipId;
+    /** Staged by onPointerMove — getCursor() has no event parameter. */
+    private isHoveringClip;
+    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;
+    /** Reset ALL instance state. Every variable must appear here. */
+    onCancel(): void;
+    private _resetState;
+}
+
+/**
+ * RippleInsertTool — Phase 2 Step 7
+ *
+ * Drag a clip from an asset and drop it onto a track.
+ * Clips at or after the drop point shift RIGHT by insertDuration.
+ * The inserted clip lands exactly at the drop point.
+ *
+ * TRANSACTION ORDER — critical:
+ *   MOVE_CLIPs first (RIGHT-TO-LEFT — +delta rule)
+ *   INSERT_CLIP last (gap is now open after all MOVE_CLIPs)
+ *
+ * INSTANCE VARIABLE GROUPS:
+ *   Group A (pending-insert): set by setPendingInsert(), preserved across drops,
+ *     cleared only by onCancel(). Cannot be changed mid-drag (guard in setPendingInsert).
+ *   Group B (drag-tracking): set by onPointerDown(), cleared by onPointerUp() and onCancel().
+ *
+ * PROVISIONAL STATE:
+ *   Ghost inserted clip (sentinel id 'provisional-insert') + all shifted right-clips.
+ *   Ghost id is NEVER written to committed state — real clip gets new id at onPointerUp.
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - onPointerMove never dispatches
+ *   - onPointerUp never mutates instance state (capture-before-reset)
+ *   - Every instance variable appears in onCancel()
+ */
+
+declare class RippleInsertTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    private pendingAsset;
+    private pendingMediaIn;
+    private pendingMediaOut;
+    private isDragging;
+    /**
+     * Configure what clip will be inserted on the next drag.
+     * Preserves across drops — can be called once per asset, then drag many times.
+     *
+     * Guard: ignored if a drag is in progress — prevents ghost/Transaction mismatch
+     * from async React state updates firing setPendingInsert mid-drag.
+     */
+    setPendingInsert(asset: Asset, mediaIn: TimelineFrame, mediaOut: TimelineFrame): void;
+    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;
+    /** Reset ALL instance state. Every variable must appear here. */
+    onCancel(): void;
+    /** Reset Group B only. Group A (pending-insert) is preserved for re-use. */
+    private _resetDragState;
+}
+
+/**
+ * HandTool — Phase 2 Step 8
+ *
+ * Scroll/pan the timeline viewport by dragging.
+ * This tool has ZERO effect on TimelineState.
+ *
+ * - Never produces a Transaction (onPointerUp returns null always)
+ * - Never calls dispatch
+ * - Never returns ProvisionalState (onPointerMove returns null always)
+ * - Never creates ClipIds (_setIdGenerator not needed)
+ *
+ * THE SCROLL CALLBACK:
+ *   The UI registers a callback via setScrollCallback().
+ *   On every onPointerMove during drag, HandTool fires:
+ *     scrollCallback(event.x - lastX)   ← pixel delta, not frame delta
+ *   The UI handles scrollLeft adjustment. HandTool has no DOM access.
+ *
+ *   The callback is optional — drag tracking activates regardless.
+ *   If no callback is registered, delta is computed but discarded.
+ *   This allows testing drag tracking without a live callback.
+ *
+ * RULES:
+ *   - Zero imports from React, DOM, @timeline/react, @timeline/ui
+ *   - Every instance variable appears in onCancel()
+ */
+
+declare class HandTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey: string;
+    /**
+     * Registered by the UI layer once at mount. Persists across drags and
+     * cancels — not per-drag state. Pass null to unregister.
+     */
+    private scrollCallback;
+    /** Gates delta computation and cursor. */
+    private isDragging;
+    /**
+     * X position (pixels) at the last pointer event.
+     * Delta is event-to-event (not from start): deltaX = event.x - lastX.
+     * Incremental delta is what UI scroll handlers expect (scrollLeft += deltaX).
+     */
+    private lastX;
+    /**
+     * Register the UI's scroll handler. Called once at mount, not per-drag.
+     * @param cb  Receives pixel deltaX per move event. Pass null to unregister.
+     */
+    setScrollCallback(cb: ((deltaX: number) => void) | null): void;
+    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;
+    /**
+     * Resets per-drag state only.
+     * scrollCallback is NOT cleared — it persists across cancels.
+     * Re-registering on every cancelled drag would be unnecessary UI burden.
+     */
+    onCancel(): void;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * SlideTool — Phase 7 Step 5
+ *
+ * Moves a clip left/right on the timeline. Neighbors trim to fill:
+ * left neighbor's end resizes to abut; right neighbor moves and resizes.
+ * No ripple — total duration unchanged.
+ *
+ * Uses: MOVE_CLIP, RESIZE_CLIP (edge 'start' | 'end').
+ * Capture-before-reset in onPointerUp.
+ */
+
+declare class SlideTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey = "Y";
+    private draggingClipId;
+    private dragStartX;
+    private originalStart;
+    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;
+}
+
+/**
+ * ZoomTool — Phase 7 Step 5
+ *
+ * Adjusts pixelsPerFrame (zoom level) via callback only.
+ * Does NOT dispatch any operations; pixelsPerFrame is UI state.
+ */
+
+type ZoomToolOptions = {
+    onZoomChange: (pixelsPerFrame: number) => void;
+    minPixelsPerFrame?: number;
+    maxPixelsPerFrame?: number;
+    initialPixelsPerFrame?: number;
+};
+declare class ZoomTool implements ITool {
+    readonly id: ToolId;
+    readonly shortcutKey = "Z";
+    private dragStartX;
+    private dragStartZoom;
+    private readonly options;
+    constructor(options: ZoomToolOptions);
+    getCursor(_ctx: ToolContext): string;
+    getSnapCandidateTypes(): readonly SnapPointType[];
+    onPointerDown(event: TimelinePointerEvent, ctx: ToolContext): void;
+    onPointerMove(event: TimelinePointerEvent, ctx: ToolContext): null;
+    onPointerUp(_event: TimelinePointerEvent, _ctx: ToolContext): null;
+    onKeyDown(event: TimelineKeyEvent, ctx: ToolContext): null;
+    onKeyUp(_event: TimelineKeyEvent, _ctx: ToolContext): void;
+    onCancel(): void;
+}
+/** Returns an ITool that wraps ZoomTool with the given options (for host registration). */
+declare function createZoomTool(options: ZoomToolOptions): ITool;
+
+/**
+ * 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' | 'state';
+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;
+};
+
+/**
+ * TrackIndex — Phase 7 Step 1
+ *
+ * Wraps IntervalTree per track for O(log n + k) getClipsAtFrame.
+ */
+
+type ClipEntry = {
+    clip: Clip;
+    track: Track;
+    trackIndex: number;
+};
+declare class TrackIndex {
+    private tree;
+    private built;
+    build(state: TimelineState): void;
+    query(frame: number): ClipEntry[];
+    get isBuilt(): boolean;
+    invalidate(): void;
+}
+
+/**
+ * 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).
+ * If index is provided and built, uses O(log n + k) lookup; else linear scan.
+ */
+declare function getClipsAtFrame(state: TimelineState, timelineFrame: TimelineFrame, index?: TrackIndex): 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.
+ * Pass optional index for O(log n + k) clip lookup.
+ */
+declare function resolveFrame(state: TimelineState, timelineFrame: TimelineFrame, quality: PlaybackQuality, dimensions: {
+    width: number;
+    height: number;
+}, index?: TrackIndex): 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;
+
+/**
+ * Centered interval tree — Phase 7 Step 1
+ *
+ * Stores intervals [start, end) and answers query(point):
+ * all intervals containing point. O(log n + k).
+ */
+type Interval<T> = {
+    readonly start: number;
+    readonly end: number;
+    readonly data: T;
+};
+declare class IntervalTree<T> {
+    private root;
+    private _size;
+    build(intervals: Interval<T>[]): void;
+    query(point: number): T[];
+    size(): number;
+}
+
+declare class PlaybackEngine {
+    private controller;
+    private pipeline;
+    private state;
+    private dimensions;
+    private trackIndex;
+    private snapManager;
+    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;
+}
+
+/**
+ * Virtual rendering contract — Phase 7 Step 2
+ *
+ * Defines what is "visible" so the React layer can mount
+ * only visible clip components.
+ */
+
+type VirtualWindow = {
+    readonly startFrame: TimelineFrame;
+    readonly endFrame: TimelineFrame;
+    readonly pixelsPerFrame: number;
+};
+type VirtualClipEntry = {
+    readonly clip: Clip;
+    readonly track: Track;
+    readonly trackIndex: number;
+    readonly isVisible: boolean;
+    readonly left: number;
+    readonly width: number;
+};
+/**
+ * Returns all clips with visibility and layout (left, width).
+ * Sorted by trackIndex ascending, then by clip timelineStart ascending.
+ */
+declare function getVisibleClips(state: TimelineState, window: VirtualWindow): VirtualClipEntry[];
+/**
+ * Builds a VirtualWindow from viewport dimensions and scroll.
+ */
+declare function getVisibleFrameRange(viewportWidth: number, scrollLeft: number, pixelsPerFrame: number): VirtualWindow;
+
+/**
+ * StateChange diff — Phase 7 Step 2
+ *
+ * Lightweight diff for hook optimization: compare prev vs next
+ * by reference so hooks can skip re-render when nothing relevant changed.
+ */
+
+type StateChange = {
+    readonly trackIds: boolean;
+    readonly clipIds: ReadonlySet<ClipId>;
+    readonly markers: boolean;
+    readonly timeline: boolean;
+    readonly playhead: boolean;
+};
+declare const EMPTY_STATE_CHANGE: StateChange;
+/**
+ * Diffs prev and next state by reference.
+ * clipIds: set of clip ids whose clip reference changed or were added/removed.
+ */
+declare function diffStates(prev: TimelineState, next: TimelineState): StateChange;
+
+/**
+ * Worker contracts — Phase 7 Step 4
+ *
+ * Core defines message/response types only.
+ * No Worker instantiation — host responsibility.
+ */
+
+type WaveformRequest = {
+    readonly requestId: string;
+    readonly assetId: AssetId;
+    readonly channel: number;
+    readonly startFrame: TimelineFrame;
+    readonly endFrame: TimelineFrame;
+    readonly buckets: number;
+    readonly sampleRate: number;
+};
+type WaveformPeak = {
+    readonly min: number;
+    readonly max: number;
+    readonly rms: number;
+};
+type WaveformResult = {
+    readonly requestId: string;
+    readonly assetId: AssetId;
+    readonly peaks: readonly WaveformPeak[];
+    readonly error?: string;
+};
+type WaveformWorkerMessage = {
+    type: 'request';
+    payload: WaveformRequest;
+} | {
+    type: 'cancel';
+    requestId: string;
+};
+type WaveformWorkerResponse = {
+    type: 'result';
+    payload: WaveformResult;
+} | {
+    type: 'progress';
+    requestId: string;
+    progress: number;
+} | {
+    type: 'error';
+    requestId: string;
+    message: string;
+};
+type ThumbnailPriority = 'high' | 'normal' | 'low';
+type ThumbnailQueueEntry = {
+    readonly request: ThumbnailRequest;
+    readonly priority: ThumbnailPriority;
+    readonly addedAt: number;
+};
+type ThumbnailWorkerMessage = {
+    type: 'request';
+    payload: ThumbnailQueueEntry;
+} | {
+    type: 'cancel';
+    requestId: string;
+} | {
+    type: 'set-priority';
+    requestId: string;
+    priority: ThumbnailPriority;
+};
+type ThumbnailWorkerResponse = {
+    type: 'result';
+    payload: ThumbnailResult;
+} | {
+    type: 'error';
+    requestId: string;
+    message: string;
+};
+
+/**
+ * ThumbnailCache — Phase 7 Step 4
+ *
+ * In-memory LRU cache for thumbnail results.
+ * No Worker — sits between pipeline and host's thumbnail provider.
+ */
+
+declare class ThumbnailCache {
+    private cache;
+    private order;
+    private maxSize;
+    constructor(maxSize?: number);
+    private key;
+    get(request: ThumbnailRequest): ThumbnailResult | null;
+    set(request: ThumbnailRequest, result: ThumbnailResult): void;
+    has(request: ThumbnailRequest): boolean;
+    invalidateClip(clipId: ClipId): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * ThumbnailQueue — Phase 7 Step 4
+ *
+ * Priority queue for thumbnail requests.
+ * Visible clips get 'high', off-screen get 'low'.
+ */
+
+declare class ThumbnailQueue {
+    private entries;
+    enqueue(request: ThumbnailRequest, priority?: ThumbnailPriority): void;
+    dequeue(): ThumbnailQueueEntry | null;
+    cancel(clipId: ClipId): void;
+    setPriority(clipId: ClipId, mediaFrame: TimelineFrame, priority: ThumbnailPriority): void;
+    get length(): number;
+    peek(): ThumbnailQueueEntry | null;
+    clear(): 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 InvariantViolation as $, type Asset as A, type Bin as B, type Clip as C, DEFAULT_AUDIO_PROPERTIES as D, DEFAULT_CLIP_TRANSFORM as E, DEFAULT_COMPRESSION_POLICY as F, DEFAULT_KEY_BINDINGS as G, type DispatchResult as H, type EDLExportOptions as I, EMPTY_STATE_CHANGE as J, type EasingCurve as K, type Effect as L, type EffectId as M, type EffectParam as N, type EffectType as O, type FCPXMLExportOptions as P, type FrameRate as Q, FrameRates as R, HOLD_EASING as S, type TimelineState as T, HandTool as U, type HistoryEntry as V, HistoryStack as W, type HistoryState as X, type ITool as Y, type Interval as Z, IntervalTree as _, type Track as a, TimelineEngine as a$, type KeyBinding as a0, KeyboardHandler as a1, type KeyboardHandlerOptions as a2, type Keyframe as a3, type KeyframeId as a4, KeyframeTool as a5, LINEAR_EASING as a6, type LinkGroup as a7, type LinkGroupId as a8, type LoopRegion as a9, RippleInsertTool as aA, RippleTrimTool as aB, RollTrimTool as aC, type RubberBandRegion as aD, type SRTParseOptions as aE, SelectionTool as aF, type SequenceSettings as aG, SerializationError as aH, SlideTool as aI, SlipTool as aJ, type SnapIndex as aK, SnapIndexManager as aL, type SnapPoint as aM, type SnapPointType as aN, type StateChange as aO, ThumbnailCache as aP, type ThumbnailPriority as aQ, type ThumbnailProvider as aR, ThumbnailQueue as aS, type ThumbnailQueueEntry as aT, type ThumbnailRequest as aU, type ThumbnailResult as aV, type ThumbnailWorkerMessage as aW, type ThumbnailWorkerResponse as aX, type TimeRange as aY, type Timecode as aZ, type Timeline as a_, type Modifiers as aa, NO_COMPRESSION as ab, NoOpTool as ac, type OTIODocument as ad, type OTIOImportOptions as ae, type OfflineAsset as af, type OperationPrimitive as ag, type PipelineConfig as ah, PlaybackEngine as ai, type PlaybackQuality as aj, type PlaybackRate as ak, PlayheadController as al, type PlayheadEvent as am, type PlayheadEventType as an, type PlayheadListener as ao, type PlayheadState as ap, type PlayheadUnsubscribe as aq, type Project as ar, type ProjectId as as, type ProvisionalManager as at, type ProvisionalState as au, type RationalTime as av, RazorTool as aw, type RejectionReason as ax, type RenderStage as ay, RippleDeleteTool as az, type TimelineFrame as b, createZoomTool as b$, type TimelineKeyAction as b0, type TimelineKeyEvent as b1, type TimelinePointerEvent as b2, type ToolContext as b3, type ToolId as b4, type ToolRegistry as b5, type TrackGroup as b6, type TrackGroupId as b7, type TrackId as b8, TrackIndex as b9, addItemToBin as bA, addTimeline as bB, browserClock as bC, buildSnapIndex as bD, canRedo as bE, canUndo as bF, checkInvariants as bG, clampFrame as bH, clearProvisional as bI, clipContainsFrame as bJ, clipsOverlap as bK, createAnimatableProperty as bL, createAsset as bM, createBin as bN, createClip as bO, createEffect as bP, createHistory as bQ, createLinkGroup as bR, createProject as bS, createProvisionalManager as bT, createRegistry as bU, createTestClock as bV, createTimeline as bW, createTimelineState as bX, createTrack as bY, createTrackGroup as bZ, createTransition as b_, type TrackType as ba, type Transaction as bb, TransactionCompressor as bc, type Transition as bd, type TransitionAlignment as be, type TransitionId as bf, type TransitionParam as bg, TransitionTool as bh, type TransitionType as bi, type VTTParseOptions as bj, type VideoDecoder as bk, type VideoFrameRequest as bl, type VideoFrameResult as bm, type ViolationType as bn, type VirtualClipEntry as bo, type VirtualWindow as bp, type WaveformPeak as bq, type WaveformRequest as br, type WaveformResult as bs, type WaveformWorkerMessage as bt, type WaveformWorkerResponse as bu, ZoomTool as bv, type ZoomToolOptions as bw, activateTool as bx, addBin as by, addFrames as bz, type AAFExportOptions as c, toProjectId as c$, defaultCaptionStyle as c0, deserializeProject as c1, deserializeTimeline as c2, diffStates as c3, dispatch as c4, exportToAAF as c5, exportToEDL as c6, exportToFCPXML as c7, exportToOTIO as c8, findMarkersByColor as c9, parseSRT as cA, parseVTT as cB, pushHistory as cC, redo as cD, reelName as cE, registerTool as cF, remapAssetPaths as cG, removeBin as cH, removeItemFromBin as cI, removeTimeline as cJ, resolveClip as cK, resolveFrame as cL, secondsToFrames as cM, serializeProject as cN, serializeTimeline as cO, setProvisional as cP, sortTrackClips as cQ, subtitleImportToOps as cR, subtractFrames as cS, toAssetId as cT, toBinId as cU, toClipId as cV, toEffectId as cW, toFCPTime as cX, toFrame as cY, toKeyframeId as cZ, toLinkGroupId as c_, findMarkersByLabel as ca, findNextClipBoundary as cb, findNextMarker as cc, findOfflineAssets as cd, findPrevClipBoundary as ce, findPrevMarker as cf, frame as cg, frameDuration as ch, frameRate as ci, frameToTimecode as cj, framesToMinutesSeconds as ck, framesToSeconds as cl, framesToTimecode as cm, getActiveTool as cn, getClipDuration as co, getClipMediaDuration as cp, getCurrentState as cq, getVisibleClips as cr, getVisibleFrameRange as cs, importFromOTIO as ct, isDropFrame as cu, isValidFrame as cv, mediaFrameForClip as cw, moveItemBetweenBins as cx, nearest as cy, nodeClock as cz, type AnimatableProperty as d, toTimecode as d0, toToolId as d1, toTrackGroupId as d2, toTrackId as d3, toTransitionId as d4, toggleSnap as d5, undo as d6, findClipById as d7, getClipsAtFrame as d8, 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 ClipEntry as q, type ClipId as r, type ClipTransform as s, type Clock as t, type CompositeLayer as u, type CompositeRequest as v, type CompositeResult as w, type Compositor as x, type CompressibleOpType as y, type CompressionPolicy as z };