@xtia/timeline 1.1.6 → 1.1.8

package/README.md

@@ -515,6 +515,14 @@ Listeners will be invoked with a [`PointEvent`](#pointevent-interface) when a se
 
 This point's position on the Timeline.
 
+##### `forwardOnly: Emitter<PointEvent>`
+
+Provides an emitter that forwards emissions triggered by forward-moving seeks.
+
+##### `reverseOnly: Emitter<PointEvent>`
+
+Provides an emitter that forwards emissions triggered by backward-moving seeks.
+
 #### Methods
 
 ##### `range(duration): TimelineRange`
@@ -543,14 +551,6 @@ Creates a `Promise` that will be resolved when the Timeline first seeks to/past
 
 The resolved value indicates the direction of the seek that triggered resolution.
 
-##### `forwardOnly(): Emitter<PointEvent>`
-
-Creates an emitter that forwards emissions triggered by forward-moving seeks.
-
-##### `reverseOnly(): Emitter<PointEvent>`
-
-Creates an emitter that forwards emissions triggered by backward-moving seeks.
-
 ##### `applyDirectional(apply, revert): UnsubscribeFunc`
 
 Registers an emission handler that calls one function for forward seeks to or past the point, and another for backward seeks from or past the point.

package/internal/emitters.d.ts

@@ -6,15 +6,7 @@ export type UnsubscribeFunc = () => void;
 export declare class Emitter<T> {
     protected onListen: ListenFunc<T>;
     protected constructor(onListen: ListenFunc<T>);
-    /**
-     * Used by tap() to create a clone of an Emitter with a redirected onListen
-     *
-     * Should be overridden in all Emitter subclasses
-     * @see {@link TimelineRange.redirect}
-     * @param listen
-     * @returns {this}
-     */
-    protected redirect(listen: ListenFunc<T>): Emitter<T>;
+    protected createTransformListen<R = T>(handler: (value: T, emit: (value: R) => void) => void): (fn: (v: R) => void) => UnsubscribeFunc;
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
      * @param handler
@@ -58,7 +50,7 @@ export declare class Emitter<T> {
      * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
-    tap(cb: Handler<T>): this;
+    tap(cb: Handler<T>): Emitter<T>;
     /**
      * Immediately passes this emitter to a callback and returns this emitter
      *
@@ -79,7 +71,6 @@ export declare class Emitter<T> {
     fork(cb: (branch: this) => void): this;
 }
 export declare class RangeProgression extends Emitter<number> {
-    protected redirect(listen: ListenFunc<number>): RangeProgression;
     /**
      * Creates a chainable progress emitter that applies an easing function to its parent's emitted values
      *
@@ -91,7 +82,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * @param from Value to interpolate from
      * @param to Value to interpolate to
@@ -101,7 +92,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * #### String interpolation
      * * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
@@ -122,7 +113,7 @@ export declare class RangeProgression extends Emitter<number> {
     /**
      * Creates a chainable emitter that interpolates two given values by progression emitted by its parent
      *
-     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, to: this): this` method
+     * Can interpolate types `number`, `number[]`, string and objects with a `blend(from: this, progression: number): this` method
      *
      * @param from Value to interpolate from
      * @param to Value to interpolate to
@@ -190,12 +181,13 @@ export declare class RangeProgression extends Emitter<number> {
      * @param check Function that takes an emitted value and returns true if the emission should be forwarded along the chain
      * @returns Listenable: emits values that pass the filter
      */
-    filter(check: (value: number) => boolean): RangeProgression;
+    filter(check: (progress: number) => boolean): RangeProgression;
     /**
      * Creates a chainable progress emitter that discards emitted values that are the same as the last value emitted by the new emitter
      * @returns Listenable: emits non-repeating values
      */
     dedupe(): RangeProgression;
+    private _dedupe?;
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
      *
@@ -214,6 +206,18 @@ export declare class RangeProgression extends Emitter<number> {
      * @returns Listenable: emits offset values
      */
     offset(delta: number): RangeProgression;
+    /**
+     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     *
+     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
+     * All listeners attached to the returned emitter receive the same values as the parent emitter.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
+     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     */
+    tap(cb: Handler<number>): RangeProgression;
 }
 export declare function createListenable<T>(onAddFirst?: () => void, onRemoveLast?: () => void): {
     listen: (fn: (v: T) => void) => UnsubscribeFunc;

package/internal/emitters.js

@@ -5,16 +5,15 @@ export class Emitter {
     constructor(onListen) {
         this.onListen = onListen;
     }
-    /**
-     * Used by tap() to create a clone of an Emitter with a redirected onListen
-     *
-     * Should be overridden in all Emitter subclasses
-     * @see {@link TimelineRange.redirect}
-     * @param listen
-     * @returns {this}
-     */
-    redirect(listen) {
-        return new Emitter(listen);
+    createTransformListen(handler) {
+        let parentUnsubscribe = null;
+        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+            handler(value, emit);
+        }), () => {
+            parentUnsubscribe();
+            parentUnsubscribe = null;
+        });
+        return listen;
     }
     /**
      * Compatibility alias for `apply()` - registers a function to receive emitted values
@@ -22,9 +21,7 @@ export class Emitter {
      * @returns A function to deregister the handler
      */
     listen(handler) {
-        return this.onListen((value) => {
-            handler(value);
-        });
+        return this.onListen(handler);
     }
     /**
      * Registers a function to receive emitted values
@@ -32,9 +29,7 @@ export class Emitter {
      * @returns A function to deregister the handler
      */
     apply(handler) {
-        return this.onListen((value) => {
-            handler(value);
-        });
+        return this.onListen(handler);
     }
     /**
      * Creates a chainable emitter that applies arbitrary transformation to values emitted by its parent
@@ -42,9 +37,8 @@ export class Emitter {
      * @returns Listenable: emits transformed values
      */
     map(mapFunc) {
-        return new Emitter(handler => this.onListen((value) => {
-            handler(mapFunc(value));
-        }));
+        const listen = this.createTransformListen((value, emit) => emit(mapFunc(value)));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that selectively forwards emissions along the chain
@@ -52,10 +46,8 @@ export class Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        return new Emitter(handler => this.onListen((value) => {
-            if (check(value))
-                handler(value);
-        }));
+        const listen = this.createTransformListen((value, emit) => check(value) && emit(value));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that discards emitted values that are the same as the last value emitted by the new emitter
@@ -66,17 +58,15 @@ export class Emitter {
      */
     dedupe(compare) {
         let previous = null;
-        return new Emitter(handler => {
-            const filteredHandler = (value) => {
-                if (!previous || (compare
-                    ? !compare(previous.value, value)
-                    : (previous.value !== value))) {
-                    handler(value);
-                    previous = { value };
-                }
-            };
-            return this.onListen(filteredHandler);
+        const listen = this.createTransformListen((value, emit) => {
+            if (!previous || (compare
+                ? !compare(previous.value, value)
+                : (previous.value !== value))) {
+                emit(value);
+                previous = { value };
+            }
         });
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
@@ -90,15 +80,11 @@ export class Emitter {
      * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
      */
     tap(cb) {
-        let parentUnsubscribe = null;
-        const { emit, listen } = createListenable(() => parentUnsubscribe = this.onListen(value => {
+        const listen = this.createTransformListen((value, emit) => {
             cb(value);
             emit(value);
-        }), () => {
-            parentUnsubscribe();
-            parentUnsubscribe = null;
         });
-        return this.redirect(listen);
+        return new Emitter(listen);
     }
     /**
      * Immediately passes this emitter to a callback and returns this emitter
@@ -123,22 +109,19 @@ export class Emitter {
     }
 }
 export class RangeProgression extends Emitter {
-    redirect(listen) {
-        return new RangeProgression(listen);
-    }
     ease(easer) {
-        if (!easer)
-            return this;
         const easerFunc = typeof easer == "string"
             ? easers[easer]
             : easer;
-        return new RangeProgression(easer ? (handler => this.onListen((progress) => {
-            handler(easerFunc(progress));
-        })) : h => this.onListen(h));
+        const listen = easerFunc
+            ? this.createTransformListen((value, emit) => emit(easerFunc(value)))
+            : this.onListen;
+        return new RangeProgression(listen);
     }
     tween(from, to) {
         const tween = createTween(from, to);
-        return new Emitter(handler => this.onListen(progress => handler(tween(progress))));
+        const listen = this.createTransformListen((progress, emit) => emit(tween(progress)));
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable emitter that takes a value from an array according to progression
@@ -154,11 +137,12 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits the sampled values
      */
     sample(source) {
-        return new Emitter(handler => this.onListen(progress => {
-            const clampedProgress = clamp(progress);
+        const listen = this.createTransformListen((value, emit) => {
+            const clampedProgress = clamp(value);
             const index = Math.floor(clampedProgress * (source.length - 1));
-            handler(source[index]);
-        }));
+            emit(source[index]);
+        });
+        return new Emitter(listen);
     }
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
@@ -183,9 +167,8 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits 0 or 1 after comparing progress with a threshold
      */
     threshold(threshold) {
-        return new RangeProgression(handler => this.onListen(progress => {
-            handler(progress >= threshold ? 1 : 0);
-        }));
+        const listen = this.createTransformListen((value, emit) => emit(value >= threshold ? 1 : 0));
+        return new RangeProgression(listen);
     }
     /**
      * Creates a chainable progress emitter that clamps incoming values
@@ -215,11 +198,13 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits scaled and repeating values
      */
     repeat(count) {
-        count = Math.max(0, count);
-        return new RangeProgression(handler => this.onListen(progress => {
-            const out = (progress * count) % 1;
-            handler(out);
-        }));
+        if (count <= 0)
+            throw new RangeError("Repeat count must be greater than 0");
+        const listen = this.createTransformListen((value, emit) => {
+            const out = (value * count) % 1;
+            emit(out);
+        });
+        return new RangeProgression(listen);
     }
     /**
      * Creates a chainable progress emitter that selectively forwards emissions along the chain
@@ -227,25 +212,28 @@ export class RangeProgression extends Emitter {
      * @returns Listenable: emits values that pass the filter
      */
     filter(check) {
-        return new RangeProgression(handler => this.onListen((value) => {
+        const listen = this.createTransformListen((value, emit) => {
             if (check(value))
-                handler(value);
-        }));
+                emit(value);
+        });
+        return new RangeProgression(listen);
     }
     /**
      * Creates a chainable progress emitter that discards emitted values that are the same as the last value emitted by the new emitter
      * @returns Listenable: emits non-repeating values
      */
     dedupe() {
-        let previous = null;
-        return new RangeProgression(handler => {
-            return this.onListen((value) => {
-                if (!previous === null || previous !== value) {
-                    handler(value);
+        if (!this._dedupe) {
+            let previous = null;
+            const listen = this.createTransformListen((value, emit) => {
+                if (previous !== value) {
+                    emit(value);
                     previous = value;
                 }
             });
-        });
+            this._dedupe = new RangeProgression(listen);
+        }
+        return this._dedupe;
     }
     /**
      * Creates a chainable progress emitter that offsets its parent's values by the given delta, wrapping at 1
@@ -267,11 +255,29 @@ export class RangeProgression extends Emitter {
     offset(delta) {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
+    /**
+     * Creates a chainable emitter that mirrors emissions from the parent emitter, invoking the provided callback `cb` as a side effect for each emission.
+     *
+     * The callback `cb` is called exactly once per parent emission, regardless of how many listeners are attached to the returned emitter.
+     * All listeners attached to the returned emitter receive the same values as the parent emitter.
+     *
+     * *Note*, the side effect `cb` is only invoked when there is at least one listener attached to the returned emitter
+     *
+     * @param cb A function to be called as a side effect for each value emitted by the parent emitter.
+     * @returns A new emitter that forwards all values from the parent, invoking `cb` as a side effect.
+     */
+    tap(cb) {
+        const listen = this.createTransformListen((value, emit) => {
+            cb(value);
+            emit(value);
+        });
+        return new RangeProgression(listen);
+    }
 }
 export function createListenable(onAddFirst, onRemoveLast) {
     const handlers = [];
     const addListener = (fn) => {
-        const unique = (v) => fn(v);
+        const unique = { fn };
         handlers.push(unique);
         if (onAddFirst && handlers.length == 1)
             onAddFirst();
@@ -286,6 +292,6 @@ export function createListenable(onAddFirst, onRemoveLast) {
     };
     return {
         listen: addListener,
-        emit: (value) => handlers.forEach(h => h(value)),
+        emit: (value) => handlers.forEach(h => h.fn(value)),
     };
 }

package/internal/point.d.ts

@@ -17,7 +17,6 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * The point's absolute position on the Timeline
      */
     position: number);
-    protected redirect(listen: ListenFunc<PointEvent>): TimelinePoint;
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration
@@ -47,15 +46,17 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      */
     seek(duration: number, easer?: Easer): Promise<void>;
     /**
-     * Creates an emitter that only emits on forward-moving seeks
+     * An point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
-    forwardOnly(): Emitter<PointEvent>;
+    get forwardOnly(): Emitter<PointEvent>;
+    private _forwardOnly?;
     /**
-     * Creates an emitter that only emits on backward-moving seeks
+     * An point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
-    reverseOnly(): Emitter<PointEvent>;
+    get reverseOnly(): Emitter<PointEvent>;
+    private _reverseOnly?;
     filter(check: (event: PointEvent) => boolean): Emitter<PointEvent>;
     /**
      * Creates an emitter that forwards events emitted by seeks of a specific direction
@@ -96,4 +97,5 @@ export declare class TimelinePoint extends Emitter<PointEvent> {
      * @returns Listenable: emits non-repeating point events
      */
     dedupe(): Emitter<PointEvent>;
+    private _dedupe?;
 }

package/internal/point.js

@@ -10,9 +10,6 @@ export class TimelinePoint extends Emitter {
         this.timeline = timeline;
         this.position = position;
     }
-    redirect(listen) {
-        return new TimelinePoint(listen, this.timeline, this.position);
-    }
     /**
      * Creates a range on the Timeline, with a given duration, starting at this point
      * @param duration
@@ -44,29 +41,34 @@ export class TimelinePoint extends Emitter {
         return this.timeline.seek(this.position, duration, easer);
     }
     /**
-     * Creates an emitter that only emits on forward-moving seeks
+     * An point emitter that only emits on forward-moving seeks
      * @returns Listenable: emits forward-seeking point events
      */
-    forwardOnly() {
-        return this.filter(1);
+    get forwardOnly() {
+        if (!this._forwardOnly)
+            this._forwardOnly = this.filter(1);
+        return this._forwardOnly;
     }
     /**
-     * Creates an emitter that only emits on backward-moving seeks
+     * An point emitter that only emits on backward-moving seeks
      * @returns Listenable: emits backward-seeking point events
      */
-    reverseOnly() {
-        return this.filter(-1);
+    get reverseOnly() {
+        if (!this._reverseOnly)
+            this._reverseOnly = this.filter(-1);
+        return this._reverseOnly;
     }
     filter(arg) {
-        return new Emitter(typeof arg == "number"
-            ? handler => this.onListen(ev => {
-                if (ev.direction === arg)
-                    handler(ev);
-            })
-            : handler => this.onListen((ev) => {
-                if (arg(ev))
-                    handler(ev);
-            }));
+        const listen = this.createTransformListen(typeof arg == "number"
+            ? (value, emit) => {
+                if (value.direction === arg)
+                    emit(value);
+            }
+            : (value, emit) => {
+                if (arg(value))
+                    emit(value);
+            });
+        return new Emitter(listen);
     }
     /**
      * Creates a Promise that will be resolved when the Timeline first seeks to/past this point
@@ -112,12 +114,16 @@ export class TimelinePoint extends Emitter {
      * @returns Listenable: emits non-repeating point events
      */
     dedupe() {
-        let previous = 0;
-        return new Emitter(handler => this.onListen(event => {
-            if (event.direction !== previous) {
-                handler(event);
-                previous = event.direction;
-            }
-        }));
+        if (!this._dedupe) {
+            let previous = 0;
+            const listen = this.createTransformListen((value, emit) => {
+                if (value.direction !== previous) {
+                    previous = value.direction;
+                    emit(value);
+                }
+            });
+            this._dedupe = new Emitter(listen);
+        }
+        return this._dedupe;
     }
 }

package/internal/range.d.ts

@@ -18,7 +18,6 @@ export declare class TimelineRange extends RangeProgression {
     start: TimelinePoint, 
     /** The point on the Timeline at which this range ends */
     end: TimelinePoint);
-    protected redirect(listen: ListenFunc<number>): TimelineRange;
     /**
      * Creates two ranges by seperating one at a given point
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
@@ -33,6 +32,18 @@ export declare class TimelineRange extends RangeProgression {
      * @returns Array(count) of points
      */
     spread(count: number): TimelinePoint[];
+    /**
+     * Creates a series of evenly-spread points across the range, optionally including the range's start and end
+     * @param count Number of Points to return, including head and tail
+     * @param includeEnds
+     */
+    spread(count: number, includeEnds: boolean): TimelinePoint[];
+    /**
+     * Creates a series of evenly-spread points across the range, optionally including the range's start and end
+     * @param count Number of Points to return, including head and tail
+     * @param includeEnds
+     */
+    spread(count: number, includeStart: boolean, includeEnd: boolean): TimelinePoint[];
     /**
      * Creates the specified number of ranges, each of `(parent.duration / count)` duration, spread
      * evenly over this range

package/internal/range.js

@@ -15,9 +15,6 @@ export class TimelineRange extends RangeProgression {
         this.endPosition = end.position;
         this.duration = this.endPosition - this.startPosition;
     }
-    redirect(listen) {
-        return new TimelineRange(listen, this.timeline, this.start, this.end);
-    }
     /**
      * Creates two ranges by seperating one at a given point
      * @param position Point of separation, relative to the range's start - if omitted, the range will be separated halfway
@@ -34,15 +31,26 @@ export class TimelineRange extends RangeProgression {
             this.timeline.range(position + this.startPosition, this.duration - position),
         ];
     }
-    /**
-     * Creates a series of evenly-spread points across the range, excluding the range's start and end
-     * @param count Number of Points to return
-     * @returns Array(count) of points
-     */
-    spread(count) {
+    spread(count, includeStart = false, includeEnd = includeStart) {
+        let start = [];
+        let end = [];
+        if (includeStart) {
+            start = [this.start];
+            count--;
+        }
+        if (includeEnd) {
+            end = [this.end];
+            count--;
+        }
+        if (count == 0)
+            return [...start, ...end];
+        if (count < 0)
+            throw new Error("Invalid spread count");
         const delta = this.duration / (count + 1);
         return [
-            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta))
+            ...start,
+            ...Array(count).fill(0).map((_, idx) => this.timeline.point(idx * delta + this.startPosition + delta)),
+            ...end
         ];
     }
     /**

package/internal/timeline.d.ts

@@ -27,19 +27,31 @@ export declare class Timeline {
      * A value of 2 would double progression speed while .25 would slow it to a quarter
      */
     timeScale: number;
+    /**
+     * The current position of this Timeline's 'play head'
+     */
     get currentTime(): number;
     set currentTime(v: number);
+    /**
+     * Returns true if this Timeline is currently progressing via `play()`, otherwise false
+     */
     get isPlaying(): boolean;
+    /**
+     * Returns a fixed point at the current end of the Timeline
+     */
     get end(): TimelinePoint;
     private _currentTime;
     private _endPosition;
-    private interval;
+    private _pause;
     private points;
     private endAction;
     private ranges;
     private currentSortDirection;
     private smoothSeeker;
     private seeking;
+    /**
+     * A fixed point representing the start of this Timeline (position 0)
+     */
     readonly start: TimelinePoint;
     private _frameEvents;
     /**
@@ -135,6 +147,9 @@ export declare class Timeline {
      * Performs a smooth-seek through a range at (1000 × this.timeScale) units per second
      */
     play(range: TimelineRange, easer?: Easer): Promise<void>;
+    private playWithInterval;
+    private playWithRAF;
+    private next;
     /**
      * Stops normal progression instigated by play()
      *
@@ -154,9 +169,29 @@ export declare class Timeline {
      * @deprecated Use timeline.position += n
      */
     step(delta: number): void;
+    /**
+     * Adds a tweening range to the Timeline
+     *
+     * **Legacy API**
+     * @param start Range's start position
+     * @param duration Tween's duration
+     * @param apply Function to apply interpolated values
+     * @param from Value at start of range
+     * @param to Value at end of range
+     * @param easer Optional easing function
+     */
     tween<T extends Tweenable>(start: number | TimelinePoint, duration: number, apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
     tween<T extends Tweenable>(start: number | TimelinePoint, end: TimelinePoint, // ease migration for tl.tween(0, tl.end, ...)
     apply: (v: Widen<T>) => void, from: T, to: T, easer?: Easer | keyof typeof easers): ChainingInterface;
+    /**
+     * Adds an event at a specific position
+     *
+     * **Legacy API**
+     * @param position Position of the event
+     * @param action Handler for forward seeking
+     * @param reverse Handler for backward seeking
+     * @returns A tween/event chaining interface
+     */
     at(position: number | TimelinePoint, action?: () => void, reverse?: boolean | (() => void)): ChainingInterface;
     private createChainingInterface;
     /**

package/internal/timeline.js

@@ -3,6 +3,8 @@ import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { clamp } from "./utils";
 const default_fps = 60;
+const requestAnimFrame = globalThis?.requestAnimationFrame;
+const cancelAnimFrame = globalThis?.cancelAnimationFrame;
 const EndAction = {
     pause: 0,
     continue: 1,
@@ -16,13 +18,22 @@ export function animate(durationMs) {
         : durationMs.asMilliseconds);
 }
 export class Timeline {
+    /**
+     * The current position of this Timeline's 'play head'
+     */
     get currentTime() { return this._currentTime; }
     set currentTime(v) {
         this.seek(v);
     }
+    /**
+     * Returns true if this Timeline is currently progressing via `play()`, otherwise false
+     */
     get isPlaying() {
-        return this.interval !== null;
+        return !!this._pause;
     }
+    /**
+     * Returns a fixed point at the current end of the Timeline
+     */
     get end() {
         return this.point(this._endPosition);
     }
@@ -62,12 +73,15 @@ export class Timeline {
         this.timeScale = 1;
         this._currentTime = 0;
         this._endPosition = 0;
-        this.interval = null;
+        this._pause = null;
         this.points = [];
         this.ranges = [];
         this.currentSortDirection = 0;
         this.smoothSeeker = null;
         this.seeking = false;
+        /**
+         * A fixed point representing the start of this Timeline (position 0)
+         */
         this.start = this.point(0);
         this._frameEvents = null;
         this._progression = null;
@@ -299,9 +313,8 @@ export class Timeline {
             ? sortTweens
             : sortReverse);
     }
-    play(arg = default_fps, easer) {
-        if (this.interval !== null)
-            this.pause();
+    play(arg, easer) {
+        this._pause?.();
         if (this.smoothSeeker) {
             this.smoothSeeker.pause();
             this.smoothSeeker.seek(this.smoothSeeker.end);
@@ -311,44 +324,72 @@ export class Timeline {
             this.seek(arg.start);
             return this.seek(arg.end, arg.duration / this.timeScale, easer);
         }
+        if (arg !== undefined && requestAnimFrame) {
+            this.playWithRAF();
+            return;
+        }
+        this.playWithInterval(arg ?? default_fps);
+    }
+    playWithInterval(fps) {
         let previousTime = Date.now();
-        this.interval = setInterval(() => {
+        const interval = setInterval(() => {
             const newTime = Date.now();
             const elapsed = newTime - previousTime;
             previousTime = newTime;
             let delta = elapsed * this.timeScale;
-            if (this._currentTime + delta <= this._endPosition) {
-                this.currentTime += delta;
+            this.next(delta);
+        }, 1000 / fps);
+        this._pause = () => clearInterval(interval);
+    }
+    playWithRAF() {
+        let previousTime = null;
+        let rafId;
+        const frame = (currentTime) => {
+            if (previousTime === null) {
+                previousTime = currentTime;
+            }
+            const elapsed = currentTime - previousTime;
+            previousTime = currentTime;
+            let delta = elapsed * this.timeScale;
+            this.next(delta);
+            rafId = requestAnimFrame(frame);
+        };
+        rafId = requestAnimFrame(frame);
+        this._pause = () => cancelAnimFrame(rafId);
+    }
+    next(delta) {
+        if (this._currentTime + delta <= this._endPosition) {
+            this.currentTime += delta;
+            return;
+        }
+        // overshot; perform restart/pause endAction			
+        if (this.endAction.type == EndAction.restart) {
+            const loopRange = this.endAction.at.to(this._endPosition);
+            const loopLen = loopRange.duration;
+            if (loopLen <= 0) {
+                const target = Math.min(this._currentTime + delta, this._endPosition);
+                this.seek(target);
                 return;
             }
-            // overshot; perform restart/pause endAction			
-            if (this.endAction.type == EndAction.restart) {
-                const loopRange = this.endAction.at.to(this._endPosition);
-                const loopLen = loopRange.duration;
-                if (loopLen <= 0) {
-                    const target = Math.min(this._currentTime + delta, this._endPosition);
-                    this.seek(target);
+            while (delta > 0) {
+                const distanceToEnd = this._endPosition - this._currentTime;
+                if (delta < distanceToEnd) {
+                    this.seek(this._currentTime + delta);
                     return;
                 }
-                while (delta > 0) {
-                    const distanceToEnd = this._endPosition - this._currentTime;
-                    if (delta < distanceToEnd) {
-                        this.seek(this._currentTime + delta);
-                        return;
-                    }
-                    this.seek(this._endPosition);
-                    delta -= distanceToEnd;
-                    this.seek(this.endAction.at);
-                }
-                return;
-            }
-            if (this.endAction.type == EndAction.pause) {
                 this.seek(this._endPosition);
-                this.pause();
-                return;
+                delta -= distanceToEnd;
+                this.seek(this.endAction.at);
             }
-            this.currentTime += delta;
-        }, 1000 / arg);
+            return;
+        }
+        if (this.endAction.type == EndAction.pause) {
+            this.seek(this._endPosition);
+            this.pause();
+            return;
+        }
+        // endaction must be "continue" or "wrap"
+        this.currentTime += delta;
     }
     /**
      * Stops normal progression instigated by play()
@@ -357,10 +398,10 @@ export class Timeline {
      *
      */
     pause() {
-        if (this.interval === null)
+        if (this._pause === null)
             return;
-        clearInterval(this.interval);
-        this.interval = null;
+        this._pause();
+        this._pause = null;
     }
     step(delta = 1) {
         this.currentTime += delta * this.timeScale;
@@ -375,14 +416,36 @@ export class Timeline {
         this.range(startPosition, duration).ease(easer).tween(from, to).apply(apply);
         return this.createChainingInterface(startPosition + duration);
     }
+    /**
+     * Adds an event at a specific position
+     *
+     * **Legacy API**
+     * @param position Position of the event
+     * @param action Handler for forward seeking
+     * @param reverse Handler for backward seeking
+     * @returns A tween/event chaining interface
+     */
     at(position, action, reverse) {
         const point = typeof position == "number" ? this.point(position) : position;
-        if (reverse === true)
-            reverse = action;
-        if (action)
-            point.apply(reverse
-                ? (event => event.direction < 0 ? reverse() : action())
-                : action);
+        if (!action) {
+            if (reverse) {
+                if (reverse === true)
+                    throw new Error("Invalid call");
+                point.reverseOnly.apply(reverse);
+            }
+            return this.createChainingInterface(point.position);
+        }
+        if (reverse) {
+            if (reverse === true) {
+                point.apply(action);
+            }
+            else {
+                point.applyDirectional(action, reverse);
+            }
+        }
+        else {
+            point.forwardOnly.apply(action);
+        }
         return this.createChainingInterface(point.position);
     }
     createChainingInterface(position) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/timeline",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "repository": {
     "url": "https://github.com/tiadrop/timeline",
     "type": "github"