@xtia/timeline 0.2.4 → 1.0.0

package/index.js

@@ -1,255 +1,587 @@
 "use strict";
-// PRE-PRODUCTION / ALPHA 0.2.4
-// Copyright, 2024, Aleta Lovelace
-// Licensed under CC BY-SA 4.0 <http://creativecommons.org/licenses/by-sa/4.0/>
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dynamicEasers = exports.easers = exports.Timeline = void 0;
-const blendNumbers = (from, to, progress) => from + progress * (to - from);
-const applyTween = (tween, position) => {
-    let progress = (position - tween.time) / tween.duration;
-    const startValue = Number(typeof tween.startValue == "function" ? tween.startValue() : tween.startValue);
-    const endValue = Number(typeof tween.endValue == "function" ? tween.endValue() : tween.endValue);
-    if (progress <= 0) {
-        tween.apply(startValue);
+exports.easers = exports.Timeline = void 0;
+exports.animate = animate;
+const default_fps = 60;
+const EndAction = {
+    pause: 0,
+    continue: 1,
+    wrap: 2,
+    restart: 3,
+};
+/**
+ * Creates an autoplaying Timeline and returns a range from it
+ * @param duration
+ * @returns Object representing a range on a single-use, autoplaying Timeline
+ */
+function animate(duration) {
+    return new Timeline(true).range(0, duration);
+}
+class Timeline {
+    get currentTime() { return this._currentTime; }
+    set currentTime(v) {
+        this.seek(v);
     }
-    else if (progress >= 1) {
-        tween.apply(endValue);
+    get isPlaying() {
+        return this.interval !== null;
     }
-    else {
-        if (tween.ease)
-            progress = tween.ease(progress);
-        tween.apply(blendNumbers(startValue, endValue, progress));
+    get end() {
+        return this.point(this._endPosition);
     }
-};
-const sortEvents = (a, b) => {
-    return a.time - b.time;
-};
-const sortTweens = (a, b) => {
-    return (a.time + a.duration) - (b.time + b.duration);
-};
-const sortReverse = (a, b) => {
-    if (a.time == b.time)
-        return 1;
-    return b.time - a.time;
-};
-const copyObject = (source, properties) => Object.fromEntries(properties.map(p => [p, source[p]]));
-class Timeline {
-    tweens = [];
-    events = [];
-    _position = 0;
-    _end = 0;
-    seeking = false;
-    playInterval;
-    currentSortDirection = 0;
-    smoothSeekTimeline;
-    pauseAtEnd;
-    /**
-     * @property Sets a time at which to rewind back to 0. If `true`, looping will occur after the final tween or event.
-     */
-    loop = false;
-    /**
-     * @property Time delta multiplier to change speed. Affects `step()` and `play()`
-     */
-    timeScale = 1;
-    constructor(autoPlay = false, atEnd = "pause") {
-        if (atEnd == "pause") {
-            this.pauseAtEnd = true;
+    constructor(autoplay = false, endAction = "pause") {
+        /**
+         * Multiplies the speed at which `play()` progresses through the Timeline
+         *
+         * A value of 2 would double progression speed while .25 would slow it to a quarter
+         */
+        this.timeScale = 1;
+        this._currentTime = 0;
+        this._endPosition = 0;
+        this.interval = null;
+        this.points = [];
+        this.ranges = [];
+        this.currentSortDirection = 0;
+        this.smoothSeeker = null;
+        this.seeking = false;
+        this.start = this.point(0);
+        this.positionHandlers = [];
+        if (endAction == "loop")
+            endAction = "restart";
+        if (autoplay !== false) {
+            this.play(typeof autoplay == "number" ? autoplay : default_fps);
         }
-        else if (atEnd == "loop") {
-            this.loop = true;
+        if (typeof endAction == "object"
+            && "restartAt" in endAction) {
+            this.endAction = {
+                type: EndAction.restart,
+                at: this.point(endAction.restartAt),
+            };
         }
-        if (autoPlay !== false)
-            this.play(autoPlay === true ? 60 : autoPlay);
+        else if (typeof endAction == "object"
+            && "wrapAt" in endAction) {
+            this.endAction = {
+                type: EndAction.wrap,
+                at: this.point(endAction.wrapAt),
+            };
+        }
+        else
+            this.endAction = {
+                type: EndAction[endAction],
+                at: this.point(0),
+            };
     }
-    get position() { return this._position; }
     /**
-     * @property The final position at which an event or tween exists on this Timeline
+     * Defines a single point on the Timeline
+     *
+     * @param position
+     * @returns A point on the Timeline as specified
+     *
+     * Listenable: this point will emit a PointEvent whenever a `seek()` reaches or passes it
      */
-    get end() { return this._end; }
-    tween(startOrTween, duration, apply, from = 0, to = 1, ease) {
-        const tweenRecord = typeof startOrTween == "object" ? copyObject(startOrTween, ["apply", "duration", "ease", "endValue", "time", "startValue"]) : {
-            time: startOrTween,
-            duration,
-            startValue: from,
-            endValue: to,
-            apply,
-            ease,
+    point(position) {
+        if (position > this._endPosition)
+            this._endPosition = position;
+        const handlers = [];
+        const data = {
+            handlers,
+            position,
         };
-        this.tweens.push(tweenRecord);
-        const endTime = tweenRecord.time + tweenRecord.duration;
-        if (endTime > this._end)
-            this._end = endTime;
-        this.currentSortDirection = 0;
-        this.seek(this.position);
-        return this.createChainInterface(endTime);
+        return createEmitter(handler => {
+            if (this.seeking)
+                throw new Error("Can't add a listener while seeking");
+            // we're adding and removing points and ranges to the internal registry according to whether any subscriptions are active, to allow obsolete points and ranges to be garbage-collected
+            if (handlers.length == 0) {
+                this.points.push(data);
+                this.currentSortDirection = 0;
+            }
+            handlers.push(handler);
+            return () => {
+                const idx = handlers.indexOf(handler);
+                if (idx === -1)
+                    throw new Error("Internal error: attempting to remove a non-present handler");
+                handlers.splice(idx, 1);
+                if (handlers.length == 0) {
+                    const idx = this.points.indexOf(data);
+                    this.points.splice(idx, 1);
+                }
+            };
+        }, {
+            delta: t => this.point(position + t),
+            range: duration => this.range(position, duration),
+            to: target => {
+                const targetPosition = typeof target == "number"
+                    ? target
+                    : target.position;
+                return this.range(position, targetPosition - position);
+            },
+            position,
+        });
     }
-    at(time, apply = false, revert = false) {
-        if (time > this._end)
-            this._end = time;
-        if (apply || revert) {
-            this.events.push({ apply, revert: revert === true ? apply : revert, time });
-            this.currentSortDirection = 0;
-            if (time <= this._position && apply)
-                apply();
-        }
-        return this.createChainInterface(time);
+    range(start = 0, optionalDuration) {
+        const startPoint = typeof start == "number"
+            ? this.point(start)
+            : start;
+        const startPosition = startPoint.position;
+        const duration = optionalDuration ?? this._endPosition - startPosition;
+        if ((startPosition + duration) > this._endPosition)
+            this._endPosition = startPosition + duration;
+        const handlers = [];
+        const range = {
+            position: startPosition,
+            duration,
+            handlers,
+        };
+        const addHandler = (handler) => {
+            if (this.seeking)
+                throw new Error("Can't add a listener while seeking");
+            if (handlers.length == 0) {
+                this.ranges.push(range);
+                this.currentSortDirection = 0;
+            }
+            handlers.push(handler);
+            return () => {
+                const idx = handlers.indexOf(handler);
+                if (idx === -1)
+                    throw new Error("Internal error: attempting to remove a non-present handler");
+                handlers.splice(idx, 1);
+                if (handlers.length == 0) {
+                    const idx = this.ranges.indexOf(range);
+                    this.ranges.splice(idx, 1);
+                }
+            };
+        };
+        return createProgressEmitter(addHandler, {
+            duration,
+            start: this.point(startPosition),
+            end: this.point(startPosition + duration),
+            bisect: (position = duration / 2) => {
+                return [
+                    this.range(startPosition, position),
+                    this.range(startPosition + position, duration - position),
+                ];
+            },
+            spread: (count) => {
+                const delta = duration / (count + 1);
+                return [
+                    ...Array(count).fill(0).map((_, idx) => this.point(idx * delta + startPosition + delta))
+                ];
+            },
+            play: (easer) => {
+                this.pause();
+                this.currentTime = startPosition;
+                return this.seek(startPosition + duration, duration, easer);
+            },
+        });
     }
-    in(time, apply, revert = false) {
-        // todo, subtract lastFrameTime difference if playing? [/ done?]
-        // todo, test this
-        if (this.isPlaying)
-            time -= (new Date().getTime() - this.lastFrameTime) * this.timeScale;
-        return this.at(time + this._position, apply, revert);
+    getWrappedPosition(n) {
+        if (this.endAction.type !== EndAction.wrap)
+            return n;
+        const wrapAt = this.endAction.at?.position ?? 0;
+        if (wrapAt == 0)
+            return n % this._endPosition;
+        if (n <= this._endPosition)
+            return n;
+        const loopStart = wrapAt;
+        const segment = this._endPosition - loopStart;
+        if (segment <= 0)
+            return Math.min(n, this._endPosition);
+        const overflow = n - this._endPosition;
+        const remainder = overflow % segment;
+        return loopStart + remainder;
     }
-    seek(time, smooth = false) {
-        if (this.seeking)
-            throw new Error("Seeking is not allowed within timeline events");
-        const interrupting = this.smoothSeekTimeline;
-        if (interrupting) {
-            interrupting.pause();
-            this.smoothSeekTimeline = undefined;
+    seek(to, duration = 0, easer) {
+        const toPosition = typeof to == "number"
+            ? to
+            : to.position;
+        if (this.seeking) {
+            throw new Error("Can't seek while seeking");
+        }
+        if (this.smoothSeeker !== null) {
+            this.smoothSeeker.pause();
+            // ensure any awaits are resolved for the previous seek?
+            this.smoothSeeker.seek(this.smoothSeeker.end);
+            this.smoothSeeker = null;
         }
-        if (smooth === false)
-            return this._seek(time);
-        if (smooth === true)
-            smooth = 400;
-        this.smoothSeekTimeline = new Timeline(true);
-        this.smoothSeekTimeline.tween(0, smooth, v => this._seek(v), this._position, time, interrupting ? exports.easers.easeOut : exports.easers.easeInOut);
+        if (duration === 0) {
+            this.seekDirect(toPosition);
+            return;
+        }
+        const seeker = new Timeline(true);
+        this.smoothSeeker = seeker;
+        seeker.range(0, duration).ease(easer).tween(this.currentTime, toPosition).listen(v => this.seekDirect(v));
+        return new Promise(r => seeker.end.listen(() => r()));
     }
-    _seek(time) {
-        if (time === this._position)
+    seekDirect(toPosition) {
+        const fromPosition = this._currentTime;
+        if (toPosition === fromPosition)
             return;
-        const fromPosition = this._position;
-        const reversing = time < fromPosition;
-        const requiredSortDirection = reversing ? -1 : 1;
-        if (this.currentSortDirection != requiredSortDirection) {
-            this.events.sort(reversing ? sortReverse : sortEvents);
-            this.tweens.sort(reversing ? sortReverse : sortTweens);
-            this.currentSortDirection = requiredSortDirection;
+        const loopingTo = this.getWrappedPosition(toPosition);
+        const loopingFrom = this.getWrappedPosition(fromPosition);
+        let virtualFrom = loopingFrom;
+        let virtualTo = loopingTo;
+        const direction = toPosition > fromPosition ? 1 : -1;
+        if (direction !== this.currentSortDirection)
+            this.sortEntries(direction);
+        if (direction === 1 && loopingTo < loopingFrom) {
+            virtualFrom = loopingFrom - this._endPosition;
         }
-        this.events.forEach(ev => {
-            const eventOverlaps = reversing
-                ? (ev.time <= fromPosition) && (ev.time > time)
-                : (ev.time > fromPosition) && (ev.time <= time);
-            if (!eventOverlaps)
-                return;
-            // timeline.position and tween states reflect the event's exact position during its handler
-            this.seekTweens(ev.time);
-            this._position = ev.time;
-            if (reversing) {
-                if (ev.revert)
-                    ev.revert(); // ev.revert?.() produced a 'false not callable' error :/
-            }
-            else {
-                if (ev.apply)
-                    ev.apply();
+        else if (direction === -1 && loopingTo > loopingFrom) {
+            virtualFrom = loopingFrom + this._endPosition;
+        }
+        this.seeking = true;
+        this._currentTime = virtualFrom;
+        try {
+            this.seekPoints(virtualTo);
+            this.seekRanges(virtualTo);
+        }
+        catch (e) {
+            this.pause();
+            throw e;
+        }
+        this._currentTime = toPosition;
+        this.positionHandlers.forEach(h => h(toPosition));
+        this.seeking = false;
+    }
+    seekPoints(to) {
+        const from = this._currentTime;
+        const direction = to > from ? 1 : -1;
+        const pointsBetween = this.points.filter(direction > 0
+            ? p => p.position > from && p.position <= to
+            : p => p.position <= from && p.position > to);
+        pointsBetween.forEach(p => {
+            this.seekRanges(p.position);
+            this._currentTime = p.position;
+            const eventData = {
+                direction
+            };
+            p.handlers.forEach(h => h(eventData));
+        });
+    }
+    seekRanges(to) {
+        const fromTime = this._currentTime;
+        this.ranges.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 = clamp((to - range.position) / range.duration, 0, 1);
+                range.handlers.forEach(h => h(progress));
             }
         });
-        this.seekTweens(time);
-        this._position = time;
-        this.seeking = false;
     }
-    /**
-     * Moves the timeline forwards (or backwards given negative delta) by a specified amount, applying intersecting tweens and events
-     * Honours `loop` ending action
-     * @param delta Amount of time to move forward by. This will be affected by the `timeScale` property
-     */
-    step(delta = 1, smooth = false) {
-        this.lastFrameTime = new Date().getTime();
-        const newPosition = this._position + delta * this.timeScale;
-        const loopAt = this.loop === true ? this._end : this.loop;
-        if (loopAt === false || newPosition < loopAt) {
-            this.seek(newPosition, smooth);
-            return;
-        }
-        const loopOvershoot = newPosition - loopAt;
-        this.seek(loopAt);
-        this.seek(0);
-        this.step(loopOvershoot);
+    sortEntries(direction) {
+        this.currentSortDirection = direction;
+        this.points.sort(direction == 1
+            ? sortEvents
+            : sortReverse);
+        this.ranges.sort(direction == 1
+            ? sortTweens
+            : sortReverse);
     }
-    lastFrameTime = new Date().getTime();
-    /**
-     * Begins moving forward in time from current `position` at a rate of 1000 x `timeScale` units per second
-     * If the timeline is already playing, it will stop and resume at the specified `fps`
-     * Honours `loop` and `pause` ending actions
-     * @param fps Frames per second
-     */
-    play(fps = 60) {
-        if (this.playInterval !== null)
+    play(fps = default_fps) {
+        if (this.interval !== null)
             this.pause();
-        this.lastFrameTime = new Date().getTime();
-        this.playInterval = setInterval(() => {
-            this.step(new Date().getTime() - this.lastFrameTime);
-            if (this.pauseAtEnd && this._position >= this._end) {
+        let previousTime = Date.now();
+        this.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;
+                return;
+            }
+            // overshot; perform 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;
+                }
+                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();
-                this._position = this._end;
+                return;
             }
+            this.currentTime += delta;
         }, 1000 / fps);
     }
-    /**
-     * Pauses automatic progression started via `play()`
-     */
     pause() {
-        if (this.playInterval !== null) {
-            clearInterval(this.playInterval);
-            this.playInterval = null;
-        }
+        if (this.interval === null)
+            return;
+        clearInterval(this.interval);
+        this.interval = null;
     }
-    get isPlaying() {
-        return this.playInterval !== null;
+    step(delta = 1) {
+        this.currentTime += delta * this.timeScale;
     }
-    /**
-     * Creates a Timeline as a tween
-     * * Transposes the inner Timeline's `0` -> `innerDuration` to the parent Timeline's `startTime` -> `outerDuration`
-     * * Experimental - this functionality may change in future versions
-     * @param startTime Position on the parent Timeline at which the inner Timeline will start seeking
-     * @param outerDuration Length of time occupied on the parent Timeline by the inner Timeline
-     * @param innerDuration Duration of the inner Timeline to transpose to `startTime` -> `outerDuration`
-     * @param ease Function that takes progression (generally between 0 and 1) and returns modified progression
-     * @returns
-     */
-    createInnerTimeline(startTime, outerDuration, innerDuration = 1, ease) {
-        const innerTimeline = new Timeline(false);
-        this.tween(startTime, outerDuration, (v) => innerTimeline.seek(v), 0, innerDuration, ease);
-        return innerTimeline;
+    tween(start, durationOrToPoint, apply, from, to, easer) {
+        const startPosition = typeof start == "number"
+            ? start
+            : start.position;
+        const duration = typeof durationOrToPoint == "number"
+            ? durationOrToPoint
+            : (durationOrToPoint.position - startPosition);
+        this.range(startPosition, duration).ease(easer).tween(from, to).listen(apply);
+        return this.createChainingInterface(startPosition + duration);
     }
-    createChainInterface(timeOffset) {
+    at(position, action, reverse) {
+        const point = typeof position == "number" ? this.point(position) : position;
+        if (reverse === true)
+            reverse = action;
+        if (action)
+            point.listen(reverse
+                ? (event => event.direction < 0 ? reverse() : action)
+                : action);
+        return this.createChainingInterface(point.position);
+    }
+    createChainingInterface(position) {
         return {
-            then: (apply, revert) => {
-                return this.at(timeOffset, apply, revert);
-            },
-            thenTween: (duration, apply, from = 0, to = 0, ease) => {
-                return this.tween(timeOffset, duration, apply, from, to, ease);
+            thenTween: (duration, apply, from = 0, to = 1, easer) => {
+                return this.tween(position, duration, apply, from, to, easer);
             },
-            thenWait: (duration) => {
-                return this.at(timeOffset + duration);
+            then: (action) => this.at(position, action),
+            thenWait: (delay) => {
+                this.point(position + delay);
+                return this.createChainingInterface(position + delay);
             },
+            end: this.point(position),
         };
     }
-    seekTweens(toTime) {
-        const fromTime = this._position;
-        this.tweens.forEach((tween) => {
-            const { duration, time: start } = tween;
-            const end = start + duration;
-            // filter tweens that overlap seeked range
-            if (Math.min(start, end) <= Math.max(toTime, fromTime)
-                && Math.min(toTime, fromTime) <= Math.max(start, end)) {
-                applyTween(tween, toTime);
-            }
-        });
-    }
     /**
-     * Initialises and starts a Timeline using chained calls to specify tweens and events
-     * @param looping
-     * @returns
+     * @deprecated use `timeline.currentTime`
      */
-    static start(looping = false) {
-        const tl = new Timeline(true, looping ? "loop" : "pause");
-        tl.loop = looping;
-        return tl.at(0);
+    get position() {
+        return this._currentTime;
     }
 }
 exports.Timeline = Timeline;
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const sortEvents = (a, b) => {
+    return a.position - b.position;
+};
+const sortTweens = (a, b) => {
+    return (a.position + a.duration) - (b.position + b.duration);
+};
+const sortReverse = (a, b) => {
+    if (a.position == b.position)
+        return 1;
+    return b.position - a.position;
+};
+function tweenValue(from, to, progress) {
+    if (Array.isArray(from)) {
+        const toArr = to;
+        if (from.length != toArr.length)
+            throw new Error("Array size mismatch");
+        return from.map((v, i) => tweenValue(v, toArr[i], progress));
+    }
+    if (typeof from == "string") {
+        return blendStrings(from, to, progress);
+    }
+    if (typeof from == "number") {
+        return blendNumbers(from, to, progress);
+    }
+    if (from && typeof from == "object") {
+        if ("blend" in from) {
+            const blendableSource = from;
+            return blendableSource.blend(to, progress);
+        }
+    }
+    throw new Error("Value not recognised as Tweenable");
+}
+function blendNumbers(from, to, progress) {
+    return from + progress * (to - from);
+}
+function mergeStrings(from, to, progress) {
+    const p = Math.min(Math.max(progress, 0), 1);
+    // Fast‑path: identical strings or one is empty
+    if (from === to)
+        return from;
+    if (!from)
+        return to;
+    if (!to)
+        return from;
+    const split = (s) => {
+        // Prefer Intl.Segmenter if available (Node ≥ 14, modern browsers)
+        if (typeof Intl !== "undefined" && Intl.Segmenter) {
+            const seg = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+            return Array.from(seg.segment(s), (seg) => seg.segment);
+        }
+        // Fallback regex (covers surrogate pairs & combining marks)
+        const graphemeRegex = /(\P{Mark}\p{Mark}*|[\uD800-\uDBFF][\uDC00-\uDFFF])/gu;
+        return s.match(graphemeRegex) ?? Array.from(s);
+    };
+    const a = split(from);
+    const b = split(to);
+    const maxLen = Math.max(a.length, b.length);
+    const pad = (arr) => {
+        const diff = maxLen - arr.length;
+        if (diff <= 0)
+            return arr;
+        return arr.concat(Array(diff).fill(" "));
+    };
+    const fromP = pad(a);
+    const toP = pad(b);
+    const replaceCount = Math.floor(p * maxLen);
+    const result = new Array(maxLen);
+    for (let i = 0; i < maxLen; ++i) {
+        result[i] = i < replaceCount ? toP[i] : fromP[i];
+    }
+    while (result.length && result[result.length - 1] === " ") {
+        result.pop();
+    }
+    return result.join("");
+}
+function parseColour(code) {
+    if (code.length < 2 || !code.startsWith("#"))
+        throw new Error("Invalid colour");
+    let rawHex = code.substring(1);
+    if (rawHex.length == 1)
+        rawHex = rawHex + rawHex + rawHex;
+    if (rawHex.length == 2) {
+        const white = rawHex[0];
+        const alpha = rawHex[1];
+        rawHex = white + white + white + alpha;
+    }
+    if (rawHex.length == 3)
+        rawHex += "f";
+    if (rawHex.length == 4)
+        rawHex = rawHex.replace(/./g, c => c + c);
+    if (rawHex.length == 6)
+        rawHex += "ff";
+    return [...rawHex.matchAll(/../g)].map(hex => parseInt(hex[0], 16));
+}
+function blendColours(from, to, bias) {
+    const fromColour = parseColour(from);
+    const toColour = parseColour(to);
+    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;
+function blendStrings(from, to, progress) {
+    if (from === to || progress === 0)
+        return from;
+    const tokenise = (s) => {
+        const chunks = [];
+        let lastIdx = 0;
+        let m;
+        while ((m = tweenableTokenRegex.exec(s))) {
+            const token = m[0];
+            const prefix = s.slice(lastIdx, m.index); // literal before token
+            chunks.push({ prefix, token });
+            lastIdx = m.index + token.length;
+        }
+        // trailing literal after the last token – stored as a final chunk
+        // with an empty token (so the consumer can easily append it)
+        const tail = s.slice(lastIdx);
+        if (tail.length) {
+            chunks.push({ prefix: tail, token: "" });
+        }
+        return chunks;
+    };
+    const fromChunks = tokenise(from);
+    const toChunks = tokenise(to);
+    const tokenCount = fromChunks.filter(c => c.token).length;
+    if (tokenCount !== toChunks.filter(c => c.token).length) {
+        return mergeStrings(from, to, progress);
+    }
+    let result = "";
+    for (let i = 0, j = 0; i < fromChunks.length && j < toChunks.length;) {
+        const f = fromChunks[i];
+        const t = toChunks[j];
+        // The *prefix* (the text before the token) must be the same.
+        if (f.prefix !== t.prefix) {
+            return mergeStrings(from, to, progress);
+        }
+        // Append the unchanged prefix.
+        result += f.prefix;
+        // If we are at the *trailing* chunk (no token), just break.
+        if (!f.token && !t.token) {
+            break;
+        }
+        // Blend the token according to its kind.
+        let blended;
+        if (f.token.startsWith("#")) {
+            blended = blendColours(f.token, t.token, progress);
+        }
+        else {
+            const fNum = parseFloat(f.token);
+            const tNum = parseFloat(t.token);
+            const blendedNum = blendNumbers(fNum, tNum, progress);
+            blended = blendedNum.toString();
+        }
+        result += blended;
+        // Advance both pointers.
+        i++;
+        j++;
+    }
+    return result;
+}
+;
+function createEmitter(onListen, api) {
+    const emitter = Object.create(api ?? {}, {
+        listen: {
+            value: (handler) => {
+                const uniqueHandler = (value) => {
+                    handler(value);
+                };
+                return onListen(uniqueHandler);
+            },
+        },
+        map: {
+            value: (mapFunc) => {
+                return createEmitter(handler => {
+                    const pipedHandler = (value) => {
+                        handler(mapFunc(value));
+                    };
+                    return onListen(pipedHandler);
+                });
+            }
+        },
+    });
+    return emitter;
+}
+function createProgressEmitter(onListen, api) {
+    return createEmitter(onListen, Object.create(api, {
+        ease: {
+            value: (easer) => {
+                const easerFunc = typeof easer == "string"
+                    ? exports.easers[easer]
+                    : easer;
+                return createProgressEmitter(easer ? handler => {
+                    const pipedHandler = (value) => {
+                        handler(easerFunc(value));
+                    };
+                    return onListen(pipedHandler);
+                } : onListen, {});
+            }
+        },
+        tween: {
+            value: (from, to) => createEmitter(handler => {
+                const tweenedHandler = (progress) => {
+                    const value = tweenValue(from, to, progress);
+                    handler(value);
+                };
+                return onListen(tweenedHandler);
+            })
+        }
+    }));
+}
 const overshoot = 1.70158;
 exports.easers = {
     linear: (x) => x,
@@ -297,20 +629,3 @@ exports.easers = {
     },
     pingpong: (x) => x < .5 ? x * 2 : 1 - (x - .5) * 2,
 };
-exports.dynamicEasers = {
-    average: (easers) => (x) => {
-        return easers.reduce((n, easer) => n + easer(x), 0) / easers.length;
-    },
-    blend: (fromEaser, toEaser, amount) => (x) => {
-        return blendNumbers(fromEaser(x), toEaser(x), amount);
-    },
-    sine: (freq = 2) => (x) => Math.sin(x * freq * Math.PI * 2),
-    multiply: (easer, mul) => (x) => {
-        for (let i = 0; i < mul; i++)
-            x = easer(x);
-        return x;
-    },
-    combine: (easers) => (x) => {
-        return easers.reduce((n, easer) => easer(n), x);
-    },
-};