@xtia/timeline 1.0.7 → 1.0.9

package/README.md

@@ -5,6 +5,7 @@
 **Timeline** is a general‑purpose, environment-agnostic choreography engine that lets you orchestrate any sequence of value changes; numbers, vectors, colour tokens, custom blendable objects, or arbitrary data structures.
 
 * [API Reference](#reference)
+* [Playground](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
 
 ## Basic Use:
 
@@ -21,7 +22,7 @@ timeline
     .range(0, 1000)
     .tween("#646", "#000")
     .listen(
-        value => document.body.style.backgroundColor = value
+        value => element.style.background = value
     );
 
 // add another tween to make a slow typing effect
@@ -29,15 +30,14 @@ const message = "Hi, planet!";
 timeline
     .range(500, 2000)
     .tween(0, message.length)
+    .map(n => message.substring(0, n))
     .listen(
-        n => element.textContent = message.substring(0, n)
+        s => element.textContent = s
     );
 
 // use an easing function
 timeline
-    .end
-    .delta(500)
-    .range(3000)
+    .range(0, 3000)
     .ease("bounce")
     .tween("50%", "0%")
     .listen(
@@ -85,27 +85,41 @@ asPercent
         n => progressBar.style.width = n
     );
 
-// apply easing (creates a *new* emitter)
+// apply easing
 const eased = firstFiveSeconds.ease("easeInOut");
 eased.listen(
     v => console.log(`Eased value: ${v}`)
 );
 
-// combine them
-const frames = eased
+// chain them
+range
     .tween(0, 30)
     .map(Math.floor)
     .dedupe()
     .tap(n => console.log("Showing frame #", n))
     .map(n => `animation-frame-${n}.png`)
     .listen(filename => img.src = filename);
+
+// each step in a chain is a 'pure', independent emitter that emits a
+// transformation of its parent's emissions
+const filenameEmitter = range
+    .tween(0, 3)
+    .map(Math.floor)
+    .dedupe()
+    .map(n => `animation-frame-${n}.png`);
+
+// filenameEmitter will emit filenames as the Timeline passes through 'range'.
+// it can be listened directly or further transformed
+const urlEmitter = filenameEmitter
+    .map(filename => `http://www.example.com/${filename}`);
+
 ```
 
 Range objects also provide a `play()` method that instructs the Timeline to play through that particular range:
 
 ```ts
 // play through the first two seconds of the Timeline
-timeline
+await timeline
     .range(0, 2000)
     .play();
 ```
@@ -158,7 +172,41 @@ timeline
 
 ## More on tweening
 
-Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(from: this, to: this): this`.
+Tween emitters can interpolate numbers, arrays of numbers, strings, and objects with a method `blend(from: this, to: this): this`, by the progression value emitted by their parent.
+
+```ts
+const range = timeline.range(0, 2000);
+
+// numbers
+range
+    .ease("overshootIn")
+    .tween(300, 500)
+    .listen(v => element.scrollTop = v);
+
+// number arrays
+range
+    .tween([0, 180], [360, 180])
+    .listen((angles) => pieChart.setValues(angles));
+
+// strings
+range
+    .tween("#000000", "#ff00ff")
+    .listen(v => element.style.color = v);
+
+// blendable objects
+// (T extends { blend(from: this, to: this): this })
+import { RGBA } from "@xtia/rgba";
+range
+    .tween(RGBA.parse("#c971a7"), RGBA.parse("#fff"))
+    .listen(v => element.style.background = v);
+
+import { Angle } from "@xtia/mezr";
+range
+    .tween(Angle.degrees(45), Angle.turns(.5))
+    .map(a => `rotate(${a.asDegrees}deg)`)
+    .listen(v => element.style.transform = v);
+
+```
 
 #### String interpolation
 * If the strings contain tweenable tokens (numbers, colour codes) and are otherwise identical, those tokens are interpolated
@@ -180,7 +228,7 @@ timeline
     .listen(v => document.title = v);
 ```
 
-You can try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
+Try out the [shadow tweening example at StackBlitz](https://stackblitz.com/edit/timeline-string-tween?file=src%2Fmain.ts)
 
 ## Autoplay and Looping Strategies
 
@@ -190,13 +238,13 @@ To create a Timeline that immediately starts playing, pass `true` to its constru
 // immediately fade in an element
 new Timeline(true)
     .range(0, 1000)
-    .tween(v => element.style.opacity = v);
+    .listen(v => element.style.opacity = v);
 
 // note, an `animate(duration)` function is exported for
 // disposable, single-use animations such as this:
 import { animate } from "@xtia/timeline";
 animate(1000)
-    .tween(v => element.style.opacity = v);
+    .listen(v => element.style.opacity = v);
 ```
 
 Normally a Timeline will simply stop playing when it reaches the end. This can be changed by passing a second argument (`endAction`) to the constructor.
@@ -279,7 +327,7 @@ resourceUrls.forEach(url => {
 We can pass a second argument to `seek()` to perform a 'smooth seek' over the given duration. A third argument can provide an easing function for the smooth seek process:
 
 ```ts
-timeline.seek(timeline.end, 400, "overshootIn");
+await timeline.seek(timeline.end, 400, "overshootIn");
 ```
 
 ## Backward-compatibility
@@ -366,15 +414,15 @@ Performs an interruptable 'smooth seek' to a specified position, lasting `durati
 
 Returns a Promise that will be resolved when the smooth seek is completed (or is interrupted by another seek\*).
 
-\* Resolution on interruption is not finalised in the library's design and the effect should be considered exceptional; relying on it is not recommended. Future versions might reject the promise when its seek is interrupted.
+\* If a smooth seek is interrupted by another seek, the interrupted seek will immediately complete before the new seek is applied, to ensure any resulting state reflects expectations set by the first seek.
 
 ##### `play(): void`
 
-Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating 60 times per second.
+Begins playing through the Timeline, from its current position, at (1000 × `timeScale`) units per second, updating 60 times per second.
 
 ##### `play(fps): void`
 
-Begins playing through the Timeline, from its current position, at (1000 x `timeScale`) units per second, updating `fps` times per second.
+Begins playing through the Timeline, from its current position, at (1000 × `timeScale`) units per second, updating `fps` times per second.
 
 ##### `tween<T>(start, duration, apply, from, to, easer?): `[`ChainingInterface`](#chaininginterface-interface)
 

package/index.js

@@ -1,15 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = exports.RangeProgression = exports.Emitter = exports.TimelineRange = exports.TimelinePoint = exports.animate = exports.Timeline = void 0;
-var timeline_1 = require("./internal/timeline");
-Object.defineProperty(exports, "Timeline", { enumerable: true, get: function () { return timeline_1.Timeline; } });
-Object.defineProperty(exports, "animate", { enumerable: true, get: function () { return timeline_1.animate; } });
-var point_1 = require("./internal/point");
-Object.defineProperty(exports, "TimelinePoint", { enumerable: true, get: function () { return point_1.TimelinePoint; } });
-var range_1 = require("./internal/range");
-Object.defineProperty(exports, "TimelineRange", { enumerable: true, get: function () { return range_1.TimelineRange; } });
-var emitters_1 = require("./internal/emitters");
-Object.defineProperty(exports, "Emitter", { enumerable: true, get: function () { return emitters_1.Emitter; } });
-Object.defineProperty(exports, "RangeProgression", { enumerable: true, get: function () { return emitters_1.RangeProgression; } });
-var easing_1 = require("./internal/easing");
-Object.defineProperty(exports, "easers", { enumerable: true, get: function () { return easing_1.easers; } });
+export { Timeline, animate } from "./internal/timeline";
+export { TimelinePoint } from "./internal/point";
+export { TimelineRange } from "./internal/range";
+export { Emitter, RangeProgression } from "./internal/emitters";
+export { easers } from "./internal/easing";

package/internal/easing.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.easers = void 0;
 const overshoot = 1.70158;
-exports.easers = {
+export const easers = {
     linear: (x) => x,
     easeIn: (x) => x * x,
     easeIn4: (x) => Math.pow(x, 4),

package/internal/emitters.d.ts

@@ -1,5 +1,5 @@
 import { Easer, easers } from "./easing";
-import { Tweenable } from "./tween";
+import { BlendableWith, Tweenable } from "./tween";
 type Handler<T> = (value: T) => void;
 export type ListenFunc<T> = (handler: Handler<T>) => UnsubscribeFunc;
 export type UnsubscribeFunc = () => void;
@@ -8,6 +8,7 @@ export declare class Emitter<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
@@ -123,6 +124,7 @@ export declare class RangeProgression extends Emitter<number> {
      * @returns Listenable: emits interpolated values
      */
     tween<T extends Tweenable>(from: T, to: T): Emitter<T>;
+    tween<T extends BlendableWith<T, R>, R>(from: T, to: R): Emitter<T>;
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
      *
@@ -182,7 +184,7 @@ export declare class RangeProgression extends Emitter<number> {
      *‎	1
      *‎	 |  /
      *‎	o| /
-     *‎	u|/      __ delta=.5
+     *‎	u|/       __ delta=.5
      *‎	t|     /
      *‎	 |    /
      *‎	 |___/__

package/internal/emitters.js

@@ -1,14 +1,12 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RangeProgression = exports.Emitter = void 0;
-const easing_1 = require("./easing");
-const tween_1 = require("./tween");
-const utils_1 = require("./utils");
-class Emitter {
+import { easers } from "./easing";
+import { tweenValue } from "./tween";
+import { clamp } from "./utils";
+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
@@ -124,8 +122,7 @@ class Emitter {
         return this;
     }
 }
-exports.Emitter = Emitter;
-class RangeProgression extends Emitter {
+export class RangeProgression extends Emitter {
     constructor() {
         super(...arguments);
         this.redirect = (listen) => new RangeProgression(listen);
@@ -134,14 +131,14 @@ class RangeProgression extends Emitter {
         if (!easer)
             return this;
         const easerFunc = typeof easer == "string"
-            ? easing_1.easers[easer]
+            ? easers[easer]
             : easer;
         return new RangeProgression(easer ? (handler => this.onListen((progress) => {
             handler(easerFunc(progress));
         })) : h => this.onListen(h));
     }
     tween(from, to) {
-        return new Emitter(handler => this.onListen(progress => handler((0, tween_1.tweenValue)(from, to, progress))));
+        return new Emitter(handler => this.onListen(progress => handler(tweenValue(from, to, progress))));
     }
     /**
      * Creates a chainable progress emitter that quantises progress, as emitted by its parent, to the nearest of `steps` discrete values.
@@ -156,7 +153,7 @@ class RangeProgression extends Emitter {
         }
         return new RangeProgression(handler => this.onListen(progress => {
             const snapped = Math.round(progress * steps) / steps;
-            handler((0, utils_1.clamp)(snapped, 0, 1));
+            handler(clamp(snapped, 0, 1));
         }));
     }
     /**
@@ -177,7 +174,7 @@ class RangeProgression extends Emitter {
      * @returns Listenable: emits clamped progression values
      */
     clamp(min = 0, max = 1) {
-        return new RangeProgression(handler => this.onListen(progress => handler((0, utils_1.clamp)(progress, min, max))));
+        return new RangeProgression(handler => this.onListen(progress => handler(clamp(progress, min, max))));
     }
     /**
      * Creates a chainable progress emitter that maps incoming values to a repeating linear scale
@@ -237,7 +234,7 @@ class RangeProgression extends Emitter {
      *‎	1
      *‎	 |  /
      *‎	o| /
-     *‎	u|/      __ delta=.5
+     *‎	u|/       __ delta=.5
      *‎	t|     /
      *‎	 |    /
      *‎	 |___/__
@@ -251,4 +248,3 @@ class RangeProgression extends Emitter {
         return new RangeProgression(handler => this.onListen(value => handler((value + delta) % 1)));
     }
 }
-exports.RangeProgression = RangeProgression;

package/internal/point.d.ts

@@ -2,7 +2,7 @@ import { Emitter, ListenFunc } from "./emitters";
 import { TimelineRange } from "./range";
 import { Timeline } from "./timeline";
 export type PointEvent = {
-    direction: -1 | 1;
+    readonly direction: -1 | 1;
 };
 export declare class TimelinePoint extends Emitter<PointEvent> {
     private timeline;

package/internal/point.js

@@ -1,8 +1,5 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimelinePoint = void 0;
-const emitters_1 = require("./emitters");
-class TimelinePoint extends emitters_1.Emitter {
+import { Emitter } from "./emitters";
+export class TimelinePoint extends Emitter {
     /** @internal Manual construction of TimelinePoint is outside of the API contract and subject to undocumented change */
     constructor(onListen, timeline, 
     /**
@@ -42,4 +39,3 @@ class TimelinePoint extends emitters_1.Emitter {
         return this.timeline.point(this.position + timeOffset);
     }
 }
-exports.TimelinePoint = TimelinePoint;

package/internal/range.d.ts

@@ -8,6 +8,10 @@ export declare class TimelineRange extends RangeProgression {
     /** The duration of this range */
     readonly duration: number;
     private endPosition;
+    /** The point on the Timeline at which this range begins */
+    readonly start: TimelinePoint;
+    /** The point on the Timeline at which this range ends */
+    readonly end: TimelinePoint;
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
     constructor(onListen: ListenFunc<number>, timeline: Timeline, startPosition: number, 
     /** The duration of this range */
@@ -52,9 +56,15 @@ export declare class TimelineRange extends RangeProgression {
      * @returns true if the provided point is within the range
      */
     contains(point: TimelinePoint): boolean;
+    /**
+     * Checks if a range is fully within this range
+     * @param range The range to check
+     * @returns true if the provided range is within the parent
+     */
     contains(range: TimelineRange): boolean;
-    /** The point on the Timeline at which this range begins */
-    readonly start: TimelinePoint;
-    /** The point on the Timeline at which this range ends */
-    readonly end: TimelinePoint;
+    overlaps(range: TimelineRange): boolean;
+    overlaps(range: {
+        position: number;
+        duration: number;
+    }): boolean;
 }

package/internal/range.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TimelineRange = void 0;
-const emitters_1 = require("./emitters");
-const point_1 = require("./point");
-const utils_1 = require("./utils");
-class TimelineRange extends emitters_1.RangeProgression {
+import { RangeProgression } from "./emitters";
+import { TimelinePoint } from "./point";
+import { clamp } from "./utils";
+export class TimelineRange extends RangeProgression {
     /** @internal Manual construction of RangeProgression is outside of the API contract and subject to undocumented change */
     constructor(onListen, timeline, startPosition, 
     /** The duration of this range */
@@ -14,9 +11,9 @@ class TimelineRange extends emitters_1.RangeProgression {
         this.startPosition = startPosition;
         this.duration = duration;
         this.redirect = (listen) => new TimelineRange(listen, this.timeline, this.startPosition, this.duration);
-        this.start = timeline.point(startPosition);
-        this.end = timeline.point(startPosition + duration);
         this.endPosition = startPosition + duration;
+        this.end = timeline.point(this.endPosition);
+        this.start = timeline.point(startPosition);
     }
     /**
      * Creates two ranges by seperating one at a given point
@@ -58,7 +55,7 @@ class TimelineRange extends emitters_1.RangeProgression {
      * @returns Listenable: this range will emit a progression value (0..1) when a `seek()` passes or intersects it
      */
     grow(delta, anchor = 0) {
-        const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+        const clampedAnchor = clamp(anchor, 0, 1);
         const leftDelta = -delta * (1 - clampedAnchor);
         const rightDelta = delta * clampedAnchor;
         const newStart = this.startPosition + leftDelta;
@@ -79,7 +76,7 @@ class TimelineRange extends emitters_1.RangeProgression {
         if (factor <= 0) {
             throw new RangeError('scale factor must be > 0');
         }
-        const clampedAnchor = (0, utils_1.clamp)(anchor, 0, 1);
+        const clampedAnchor = clamp(anchor, 0, 1);
         const oldLen = this.endPosition - this.startPosition;
         const pivot = this.startPosition + oldLen * clampedAnchor;
         const newStart = pivot - (pivot - this.startPosition) * factor;
@@ -91,10 +88,16 @@ class TimelineRange extends emitters_1.RangeProgression {
         return this.timeline.range(newStart, newEnd - newStart);
     }
     contains(target) {
-        const [targetStart, targetEnd] = target instanceof point_1.TimelinePoint
+        const [targetStart, targetEnd] = target instanceof TimelinePoint
             ? [target.position, target.position]
             : [target.startPosition, target.startPosition + target.duration];
         return targetStart >= this.startPosition && targetEnd < this.endPosition;
     }
+    overlaps(range) {
+        const [start, end] = range instanceof TimelineRange
+            ? [range.startPosition, range.endPosition]
+            : [range.position, range.position + range.duration];
+        return Math.min(this.startPosition, this.endPosition) <= Math.max(start, end) &&
+            Math.max(this.startPosition, this.endPosition) >= Math.min(start, end);
+    }
 }
-exports.TimelineRange = TimelineRange;

package/internal/timeline.d.ts

@@ -1,4 +1,5 @@
 import { Easer, easers } from "./easing";
+import { RangeProgression } from "./emitters";
 import { TimelinePoint } from "./point";
 import { TimelineRange } from "./range";
 import { Tweenable } from "./tween";
@@ -11,7 +12,7 @@ declare const EndAction: {
 };
 /**
  * Creates an autoplaying Timeline and returns a range from it
- * @param duration
+ * @param duration Animation duration, in milliseconds
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
 export declare function animate(duration: number): TimelineRange;
@@ -36,14 +37,22 @@ export declare class Timeline {
     private smoothSeeker;
     private seeking;
     readonly start: TimelinePoint;
-    private positionHandlers;
+    private progressionHandlers;
+    private _progression;
+    /**
+     * Listenable: emits a progression value (0..1) when the Timeline's internal
+     * position changes, and when the Timeline's total duration is extended
+     *
+     * **Experimental**
+     */
+    get progression(): RangeProgression;
     constructor();
     /**
-     * @param autoplay Pass `true` to begin playing at (1000 x this.timeScale) units per second immediately on creation
+     * @param autoplay Pass `true` to begin playing at (1000 × this.timeScale) units per second immediately on creation
      */
     constructor(autoplay: boolean);
     /**
-     * Creates a Timeline that begins playing immediately at (1000 x this.timeScale) units per second
+     * Creates a Timeline that begins playing immediately at (1000 × this.timeScale) units per second
      * @param autoplayFps Specifies frames per second
      */
     constructor(autoplayFps: number);
@@ -51,12 +60,12 @@ export declare class Timeline {
      * @param autoplay If this argument is `true`, the Timeline will begin playing immediately on creation. If the argument is a number, the Timeline will begin playing at the specified frames per second
      * @param endAction Specifies what should happen when the final position is passed by `play()`/`autoplay`
      *
-     * `"pause"`: **(default)** the Timeline will pause at its final position
-     * `"continue"`: The Timeline will continue progressing beyond its final position
-     * `"restart"`: The Timeline will seek back to 0 then forward to account for any overshoot and continue progressing
-     * `"wrap"`: The Timeline's position will continue to increase beyond the final position, but Points and Ranges will be activated as if looping
-     * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
-     * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
+     * * `"pause"`: **(default)** the Timeline will pause at its final position
+     * * `"continue"`: The Timeline will continue progressing beyond its final position
+     * * `"restart"`: The Timeline will seek back to 0 then forward to account for any overshoot and continue progressing
+     * * `"wrap"`: The Timeline's position will continue to increase beyond the final position, but Points and Ranges will be activated as if looping
+     * * `{restartAt: number}`: Like `"restart"` but seeking back to `restartAt` instead of 0
+     * * `{wrapAt: number}`: Like `"wrap"` but as if restarting at `wrapAt` instead of 0
      */
     constructor(autoplay: boolean | number, endAction: {
         wrapAt: number;
@@ -99,7 +108,7 @@ export declare class Timeline {
     /**
      * Smooth-seeks to a specified position
      *
-     * Aborts and replaces any on-going smooth-seek process on this Timeline
+     * Immediately completes and replaces any ongoing smooth-seek process on this Timeline
      * @param toPosition
      * @param duration Duration of the smooth-seek process in milliseconds
      * @param easer Optional easing function for the smooth-seek process
@@ -111,7 +120,7 @@ export declare class Timeline {
     private seekRanges;
     private sortEntries;
     /**
-     * Starts progression of the Timeline from its current position at (1000 x this.timeScale) units per second
+     * Starts progression of the Timeline from its current position at (1000 × this.timeScale) units per second
      */
     play(): void;
     play(fps: number): void;

package/internal/timeline.js

@@ -1,10 +1,7 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Timeline = void 0;
-exports.animate = animate;
-const point_1 = require("./point");
-const range_1 = require("./range");
-const utils_1 = require("./utils");
+import { RangeProgression } from "./emitters";
+import { TimelinePoint } from "./point";
+import { TimelineRange } from "./range";
+import { clamp } from "./utils";
 const default_fps = 60;
 const EndAction = {
     pause: 0,
@@ -14,13 +11,13 @@ const EndAction = {
 };
 /**
  * Creates an autoplaying Timeline and returns a range from it
- * @param duration
+ * @param duration Animation duration, in milliseconds
  * @returns Object representing a range on a single-use, autoplaying Timeline
  */
-function animate(duration) {
+export function animate(duration) {
     return new Timeline(true).range(0, duration);
 }
-class Timeline {
+export class Timeline {
     get currentTime() { return this._currentTime; }
     set currentTime(v) {
         this.seek(v);
@@ -31,6 +28,17 @@ class Timeline {
     get end() {
         return this.point(this._endPosition);
     }
+    /**
+     * Listenable: emits a progression value (0..1) when the Timeline's internal
+     * position changes, and when the Timeline's total duration is extended
+     *
+     * **Experimental**
+     */
+    get progression() {
+        if (this._progression === null)
+            this._progression = new TimelineProgressionEmitter(this.progressionHandlers);
+        return this._progression;
+    }
     constructor(autoplay = false, endAction = "pause") {
         /**
          * Multiplies the speed at which `play()` progresses through the Timeline
@@ -47,7 +55,8 @@ class Timeline {
         this.smoothSeeker = null;
         this.seeking = false;
         this.start = this.point(0);
-        this.positionHandlers = [];
+        this.progressionHandlers = [];
+        this._progression = null;
         if (endAction == "loop")
             endAction = "restart";
         if (autoplay !== false) {
@@ -82,8 +91,10 @@ class Timeline {
      * Listenable: this point will emit a PointEvent whenever a `seek()` reaches or passes it
      */
     point(position) {
-        if (position > this._endPosition)
+        if (position > this._endPosition) {
             this._endPosition = position;
+            this.progressionHandlers.slice().forEach(h => h(this._currentTime / position));
+        }
         const handlers = [];
         const data = {
             handlers,
@@ -109,7 +120,7 @@ class Timeline {
                 }
             };
         };
-        return new point_1.TimelinePoint(addHandler, this, position);
+        return new TimelinePoint(addHandler, this, position);
     }
     range(start = 0, optionalDuration) {
         const startPoint = typeof start == "number"
@@ -117,9 +128,9 @@ class Timeline {
             : start;
         const startPosition = startPoint.position;
         const duration = optionalDuration ?? this._endPosition - startPosition;
-        const endPosition = startPosition + duration;
-        if (endPosition > this._endPosition)
-            this._endPosition = endPosition;
+        // const endPosition = startPosition + duration;
+        //if (endPosition > this._endPosition) this._endPosition = endPosition;
+        // ^ leave this to range's point() calls
         const handlers = [];
         const range = {
             position: startPosition,
@@ -145,7 +156,7 @@ class Timeline {
                 }
             };
         };
-        return new range_1.TimelineRange(addHandler, this, startPosition, duration);
+        return new TimelineRange(addHandler, this, startPosition, duration);
     }
     getWrappedPosition(n) {
         if (this.endAction.type !== EndAction.wrap)
@@ -172,7 +183,7 @@ class Timeline {
         }
         if (this.smoothSeeker !== null) {
             this.smoothSeeker.pause();
-            // ensure any awaits are resolved for the previous seek?
+            // ensure any awaits are resolved for the previous seek
             this.smoothSeeker.seek(this.smoothSeeker.end);
             this.smoothSeeker = null;
         }
@@ -213,7 +224,6 @@ class Timeline {
             throw e;
         }
         this._currentTime = toPosition;
-        this.positionHandlers.slice().forEach(h => h(toPosition));
         this.seeking = false;
     }
     seekPoints(to) {
@@ -222,27 +232,25 @@ class Timeline {
         const pointsBetween = this.points.filter(direction > 0
             ? p => p.position > from && p.position <= to
             : p => p.position <= from && p.position > to);
+        const eventData = {
+            direction
+        };
         pointsBetween.slice().forEach(p => {
             this.seekRanges(p.position);
             this._currentTime = p.position;
-            const eventData = {
-                direction
-            };
             p.handlers.slice().forEach(h => h(eventData));
         });
     }
     seekRanges(to) {
-        const fromTime = this._currentTime;
+        const seekRange = this.point(Math.min(this._currentTime, to))
+            .to(Math.max(this._currentTime, to));
         this.ranges.slice().forEach((range) => {
-            const { duration, position } = range;
-            const end = position + duration;
-            // filter ranges that overlap seeked range
-            if (Math.min(position, end) <= Math.max(to, fromTime)
-                && Math.min(to, fromTime) <= Math.max(position, end)) {
-                let progress = (0, utils_1.clamp)((to - range.position) / range.duration, 0, 1);
+            if (seekRange.overlaps(range)) {
+                let progress = clamp((to - range.position) / range.duration, 0, 1);
                 range.handlers.slice().forEach(h => h(progress));
             }
         });
+        this.progressionHandlers.slice().forEach(h => h(this._currentTime / this._endPosition));
     }
     sortEntries(direction) {
         this.currentSortDirection = direction;
@@ -344,7 +352,18 @@ class Timeline {
         return this._currentTime;
     }
 }
-exports.Timeline = Timeline;
+class TimelineProgressionEmitter extends RangeProgression {
+    constructor(handlers) {
+        super((handler) => {
+            const unique = (n) => handler(n);
+            handlers.push(unique);
+            return () => {
+                const idx = handlers.indexOf(unique);
+                handlers.splice(idx, 1);
+            };
+        });
+    }
+}
 const sortEvents = (a, b) => {
     return a.position - b.position;
 };

package/internal/tween.d.ts

@@ -4,5 +4,8 @@ export type Tweenable = number | number[] | string | Blendable;
 export interface Blendable {
     blend(target: this, progress: number): this;
 }
+export interface BlendableWith<T, R> {
+    blend(target: R, progress: number): T;
+}
 /** @internal */
 export declare function tweenValue<T extends Tweenable>(from: T, to: T, progress: number): T;

package/internal/tween.js

@@ -1,9 +1,6 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.tweenValue = tweenValue;
-const utils_1 = require("./utils");
+import { clamp } from "./utils";
 /** @internal */
-function tweenValue(from, to, progress) {
+export function tweenValue(from, to, progress) {
     if (Array.isArray(from)) {
         const toArr = to;
         if (from.length != toArr.length)
@@ -89,7 +86,7 @@ function parseColour(code) {
 function blendColours(from, to, bias) {
     const fromColour = parseColour(from);
     const toColour = parseColour(to);
-    const blended = fromColour.map((val, i) => (0, utils_1.clamp)(blendNumbers(val, toColour[i], bias), 0, 255));
+    const blended = fromColour.map((val, i) => clamp(blendNumbers(val, toColour[i], bias), 0, 255));
     return ("#" + blended.map(n => Math.round(n).toString(16).padStart(2, "0")).join("")).replace(/ff$/, "");
 }
 const tweenableTokenRegex = /(#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b|[-+]?\d*\.?\d+(?:[eE][-+]?\d+)?)/g;

package/internal/utils.js

@@ -1,6 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.clamp = void 0;
 /** @internal */
-const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
-exports.clamp = clamp;
+export const clamp = (value, min, max) => Math.min(Math.max(value, min), max);

package/package.json

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