import type { AnimationHandle } from '../value/animatable';
import type { LifecycleCallbacks } from '../value/lifecycle';
/** 'physics' = a live spring/decay (target-chase); 'timeline' = a tween or baked table (seekable). */
export type MotionKind = 'physics' | 'timeline';
/**
 * A superset of AnimationHandle: every `{ finished, stop }` consumer keeps
 * working, while opt-in users get pause / timeScale / reverse / seek / progress.
 * Kind-invalid controls warn once and no-op, never throw (the warnOnce house
 * convention). The `kind` / `seekable` flags make the spring-vs-tween split
 * self-describing.
 */
export interface PlaybackHandle extends AnimationHandle {
    /** 'physics' = live spring/decay; 'timeline' = tween or baked table. */
    readonly kind: MotionKind;
    /** True once seekable: always for tweens, for physics only after a successful bake(). */
    readonly seekable: boolean;
    /** Freeze the accumulator AND unsubscribe so the loop can sleep. Resumable. */
    pause(): this;
    /** Resume real time. No-op if not paused. */
    play(): this;
    /** Alias of play(). */
    resume(): this;
    isPaused(): boolean;
    /** Time dilation; the step size stays 1/120 so the trajectory shape is unchanged. 0 acts like pause. */
    timeScale(rate: number): this;
    timeScale(): number;
    /** Tween/baked: play the curve backward (lossless). Live physics: retarget to start, velocity conserved. */
    reverse(): this;
    /** Jump the playhead to an absolute time (ms). */
    seek(timeMs: number): this;
    /** Read/write normalized progress 0..1. Getter returns 1 for a settled or reduced handle. */
    progress(p: number): this;
    progress(): number;
    /** Local elapsed time (ms), excluding repeats. */
    time(): number;
    /** Total elapsed (ms), including repeats and repeatDelay. */
    totalTime(): number;
    /** Duration (ms); undefined for an un-baked live spring/decay. */
    duration(): number | undefined;
    /** True while the run is progressing (not finished/stopped, not paused). */
    isActive(): boolean;
    /** Current iteration index, 0-based (advances at each repeat boundary). */
    iteration(): number;
    /**
     * Progress across the WHOLE run, 0..1 (initial delay + every iteration + repeat
     * delays). Falls back to the current iteration's progress for an un-baked spring
     * or an infinite repeat (no finite total). 1 once settled.
     */
    totalProgress(): number;
    /** Replay from the start (skipping the initial delay) and play. No-op + warn once on a finished handle. */
    restart(): this;
    /** The initial delay (ms) before the first iteration - the run's own start offset. */
    startTime(): number;
    /** When the whole run completes (ms from its start): delay + all iterations. undefined if unknown/infinite. */
    endTime(): number | undefined;
    /**
     * Sample the deterministic trajectory to rest ONCE into a seekable table.
     * Idempotent; no-op on a tween or an already-baked handle. Returns true on
     * success, false (seekable stays false, warns once) if the motion never rests.
     */
    bake(options?: {
        maxDurationMs?: number;
    }): boolean;
    /** Live re-aim conserving current velocity. Warn once + no-op on a tween. The scroll-chase verb. */
    setTarget(value: number, options?: {
        velocity?: number;
    }): this;
}
export interface PlaybackOptions extends LifecycleCallbacks<PlaybackHandle> {
    /** ms before the clip starts, on the frame clock (background-tab-safe), scaled by timeScale. */
    delay?: number;
    /** Iterations beyond the first. Infinity = forever (finished never resolves; stop() resolves it). */
    repeat?: number;
    /** Dead time (ms) between iterations, on the frame clock. */
    repeatDelay?: number;
    /** Ping-pong: a tween mirrors the curve, a spring alternates start<->target. Default false. */
    yoyo?: boolean;
    /** Start under author control instead of auto-playing. Default false. */
    paused?: boolean;
    /** Initial time scale. Default 1. */
    timeScale?: number;
}
//# sourceMappingURL=handle.d.ts.map