feat(Timeline): e2e visual tests + restart boundary alignment fix

Two related workstreams on the feat/timeline branch:

### 1. E2E visual regression testing (examples 03, 20, 21, 22)

Added Playwright-based e2e tests with visual snapshot regression for the
timeline and graphs examples. Uses a deterministic requestAnimationFrame hijack
(__tickFrame/__advanceTo) so timeline tests produce identical output every
run — no real-time frame variance.

- e2e/graphs.spec.ts — snapshot of the 03_graphs easing curve thumbnails
  (waits for fonts via document.fonts.ready to prevent cross-platform diff).
- e2e/timeline.spec.ts — 3 test suites:
  - 20_timeline — sequential, parallel, and label-based animation (16 frames
    at 200ms steps, 0–3000ms).
  - 21_timeline_slider — slider-driven scrubbing forward (17 frames at 400ms
    steps, 0–6400ms) and backward (17 frames, 6400→0ms), without rAF hijack
    (no animation loop — purely slider input events).
  - 22_timeline_repeat — repeat×3, yoyo, and yoyo+repeat×2 animation (16
    frames at 200ms steps, 0–3000ms).
- e2e/playwright.config.ts — serves the repo via npx serve on port 3333.
- 62 baseline snapshots (.webp, Chrome on macOS).

Example fixes caught during testing:
- examples/20_timeline.html — fixed the "parallel" example (target2) so it
  actually demonstrates parallelism (y 0→200→100 instead of 0→200→0 on the
  chained third tween); wrapped the label-based inner timeline in an outer
  timeline for correct coordinated playback.
- examples/22_timeline_repeat.html — switched from X to Y axis translation
  for clearer visual distinction between boxes; added CSS color comments.
- e2e/graphs.spec.ts — switched waitUntil to networkidle and added
  document.fonts.ready to prevent font-loading snapshot diffs.

### 2. Timeline restart boundary alignment (fixes sub-frame sync drift)

Problem: When a short yoyo timeline (1200ms cycle) restarted via
timeline.start(time), _startTime was set to the wall-clock time
(~1200.024ms — one frame overshoot). Children subsequently saw
elapsedTime = t - 1200.024, a 0.024ms offset. A longer yoyo+repeat×2
timeline (2400ms cycle) avoided this because its clone at offset 1200 started
at the exact offset with no wall-clock overshoot. The offset propagated
through Quadratic.InOut easing to a ~0.016px value difference mid-cycle,
growing with variable frame timing.

Root cause: Timeline.start(time) unconditionally set _startTime = time.

Fix (3 changes in src/Timeline.ts):
- New field _nextStartTime: number | undefined — stores the ideal
  _startTime + _duration boundary when the timeline finishes.
- In update(), before returning false, store the boundary.
- In start(), use the stored boundary when time >= _nextStartTime
  (forward restart — snaps to exact boundary); fall through to time when
  time < _nextStartTime (deliberate scrub-back) or _nextStartTime is
  undefined (fresh start). Resets _lastUpdateTime = -Infinity to prevent
  false scrub-back detection on restart.

Backward compatibility: All 1063 unit assertions pass. Scrub-back test
updated — children not yet reached in forward play now preserve their stale
forward-play values rather than eagerly snapping to start values.

Documentation: dev-docs/02-timeline-restart-boundary-alignment.md —
full write-up with concrete frame data showing the before/after diff.

Author: trusktr

NOTES.md

@@ -14,5 +14,9 @@ library. User-facing docs live in `examples/` and `README.md`.
 
 - **01 — Timeline.update() scrub-back detection** [`dev-docs/01-timeline-update-scrub-detection.md`](dev-docs/01-timeline-update-scrub-detection.md)
   Fixes an auto-restart bug where late-offset children overwrote early children
-  at the start of a restarted cycle. Introduces `_lastUpdateTime` traking and
+  at the start of a restarted cycle. Introduces `_lastUpdateTime` tracking and
   direction-aware eager-restart/clamp gating in `update()`. ✅
+- **02 — Timeline restart boundary alignment** [`dev-docs/02-timeline-restart-boundary-alignment.md`](dev-docs/02-timeline-restart-boundary-alignment.md)
+  Fixes a sub-frame timing drift between repeated short timelines and longer
+  equivalent timelines. Stores the ideal `_startTime + _duration` boundary
+  on finish and snaps `start()` to it. ✅

dev-docs/02-timeline-restart-boundary-alignment.md

@@ -0,0 +1,127 @@
+# 02 — Timeline restart boundary alignment
+
+**Date:** 2026-09-21
+**Status:** ✅ Implemented
+
+## Problem
+
+When a running timeline finishes and the application restarts it via
+`timeline.start(time)`, the `_startTime` was set to the current wall-clock
+`time`. In a real browser (or hijacked rAF test environment), the frame time
+almost never lands exactly on the correct duration boundary (e.g., 1200 ms).
+This creates a sub-frame offset in the new cycle's clock.
+
+### Concrete example (22_timeline_repeat)
+
+```js
+// yoyo timeline (1200 ms cycle)
+tl.add(new Tween(target2.dataset).to({y: 200}, 600).easing(Easing.Quadratic.InOut), {yoyo: true})
+
+// yoyo+repeat timeline (2400 ms cycle)
+tl.add(new Tween(target3.dataset).to({y: 200}, 600).easing(Easing.Quadratic.InOut), {yoyo: true, repeat: 2})
+```
+
+The `yoyo` timeline finishes at frame time ~1200.024 ms (frame interval ~16.667
+ms). Its `start` call sets `_startTime = 1200.024`. Children at offset 0
+subsequently see `elapsedTime = t - 1200.024`, a 0.024 ms offset.
+
+The `yoyo+repeat:2` timeline does NOT restart at 1200 ms. Instead, its forward
+clone at offset 1200 starts with `child.start(1200)` — the **exact** offset, no
+wall-clock overshoot. It subsequently sees `elapsedTime = t - 1200`.
+
+At frame t ≈ 1216.691 ms, these two elapsed times are:
+
+- yoyo: `16.667` (1216.691 − 1200.024 = 16.667)
+- yoyo+repeat: `16.691` (1216.691 − 1200 = 16.691)
+
+This 0.024 ms difference in elapsed propagates through the Quadratic.InOut
+easing, reaching **~0.016 px** value difference mid-cycle (at the steepest part
+of the curve). In a real browser with variable frame timing, the offset can be
+larger and compound further.
+
+### Snapshot data before fix
+
+```
+t=  1500: y2=100.004000, y3=100.019999 diff=0.015999 ***
+t=  2100: y2= 99.988000, y3= 99.972002 diff=0.015998 ***
+t=  2400: y2=  0.000000, y3=  0.000000 diff=0.000000 (resync)
+```
+
+After the fix, both targets produce identical values at every frame:
+
+```
+t=  1500: y2=100.019999, y3=100.019999 diff=0.000000
+t=  2100: y2= 99.972002, y3= 99.972002 diff=0.000000
+```
+
+## Root cause
+
+In `Timeline.start(time)`, the `_startTime` was unconditionally set to the
+wall-clock `time` parameter. When the timeline restarts after finishing, `time`
+overshoots the ideal cycle boundary by up to one frame interval, creating a
+permanent sub-frame offset in the next cycle's clock.
+
+The longer `yoyo+repeat:2` timeline avoids this because its extra clips start at
+precise offsets (1200, 1800) within the single longer cycle — no restart, no
+wall-clock overshoot.
+
+## Fix (3 locations, `src/Timeline.ts`)
+
+### 1. New field `_nextStartTime`
+
+```ts
+private _nextStartTime: number | undefined
+```
+
+Stored when the timeline finishes — the **ideal** next-cycle boundary.
+
+### 2. Store the boundary in `update()`
+
+```ts
+if (this._duration === 0 || time >= this._startTime + this._duration) {
+    if (this._onCompleteCallback) this._onCompleteCallback(this)
+    // Store the ideal next-cycle boundary so start() snaps to it
+    // instead of the overshooting wall-clock time.
+    this._nextStartTime = this._startTime + this._duration
+    this._isPlaying = false
+    return false
+}
+```
+
+Before returning `false`, the ideal boundary `_startTime + _duration` is stored.
+For the first finish of the yoyo timeline (duration 1200 ms, `_startTime`
+initially 0), this stores 1200 — exactly where the next cycle should begin.
+
+### 3. Conditionally use the boundary in `start()`
+
+```ts
+// Snap to the ideal cycle boundary when restarting a finished
+// timeline, so repeated timelines stay in sync with longer ones.
+// Only when the caller's time is at or past the boundary;
+// a time before the boundary means a deliberate scrub-back.
+this._startTime = this._nextStartTime !== undefined && time >= this._nextStartTime ? this._nextStartTime : time
+this._nextStartTime = undefined
+```
+
+- **`time >= _nextStartTime`** (forward restart): Uses the stored boundary.
+  The yoyo timeline's restart at time 1200.024 sees `1200.024 >= 1200` → uses
+  `1200`. Children see `elapsedTime = t - 1200`, perfectly aligned with the
+  longer timeline's clone.
+- **`time < _nextStartTime`** (scrub-back): Falls through to `time`. Preserves
+  the existing scrub-to-start behavior tested in the unit suite.
+- **`_nextStartTime` undefined** (fresh start): Falls through to `time`. No
+  change for initial starts.
+
+## Backward compatibility
+
+All 1063 unit assertions pass. E2E visual regression snapshots updated. The
+scrub-back test (`Timeline scrubbing back to start restores start values`)
+correctly triggers the `time < _nextStartTime` branch and preserves the original
+`start(time)` semantics.
+
+## Affected code
+
+| File                              | Change                                                        |
+| --------------------------------- | ------------------------------------------------------------- |
+| `src/Timeline.ts`                 | +`_nextStartTime` field, store boundary in `update()`, use in `start()` |
+| `e2e/timeline.spec.ts-snapshots/` | Updated snapshots for `22_timeline_repeat` test               |

dist/tween.amd.js

@@ -578,9 +578,7 @@ define(['exports'], (function (exports) { 'use strict';
                         temp.push(value);
                     }
                     if (isInterpolationList) {
-                        // if (_valuesStart[property] === undefined) { // handle end values only the first time. NOT NEEDED? setupProperties is now guarded by _propertiesAreSetUp.
                         _valuesEnd[property] = temp;
-                        // }
                     }
                 }
                 // handle the deepness of the values
@@ -1043,6 +1041,7 @@ define(['exports'], (function (exports) { 'use strict';
             this._isPlaying = false;
             this._isPaused = false;
             this._pauseStart = 0;
+            this._lastUpdateTime = -Infinity;
             this._onStartCallbackFired = false;
             // Empty on purpose. Use `.add()` to compose.
             // Sequential by default, parallel via explicit offsets, labels, or options.
@@ -1423,7 +1422,13 @@ define(['exports'], (function (exports) { 'use strict';
             this._isPlaying = true;
             this._isPaused = false;
             this._onStartCallbackFired = false;
-            this._startTime = time;
+            // Snap to the ideal cycle boundary when restarting a finished
+            // timeline, so repeated timelines stay in sync with longer ones.
+            // Only when the caller's time is at or past the boundary;
+            // a time before the boundary means a deliberate scrub-back.
+            this._startTime = this._nextStartTime !== undefined && time >= this._nextStartTime ? this._nextStartTime : time;
+            this._nextStartTime = undefined;
+            this._lastUpdateTime = -Infinity;
             for (var _i = 0, _a = this._entries; _i < _a.length; _i++) {
                 var entry = _a[_i];
                 if (entry.node.isPlaying())
@@ -1507,26 +1512,41 @@ define(['exports'], (function (exports) { 'use strict';
             }
             var timelineLocal = time - this._startTime;
             var effectiveLocal = Math.min(timelineLocal, this._duration);
+            // Detect scrub-back vs forward play: only eagerly restart/clamp
+            // late-offset children when the playhead moved backward. On
+            // forward playback (including auto-restart), children start
+            // lazily so same-property tweens chain correctly.
+            var scrubbingBack = time < this._lastUpdateTime;
+            this._lastUpdateTime = time;
             for (var _i = 0, _a = this._entries; _i < _a.length; _i++) {
                 var entry = _a[_i];
                 var child = entry.node;
                 if (!entry.started) {
-                    // First start must wait until due; a never-started child left
-                    // behind stays untouched. (Later re-starts are harmless and
-                    // handled below, since Tween keeps its captured setup.)
+                    // First start must wait until due; a never-started child
+                    // left behind stays untouched.
                     if (effectiveLocal < entry.offset)
                         continue;
                     child.start(entry.offset);
                     entry.started = true;
                 }
                 else if (!child.isPlaying() && effectiveLocal < entry.offset + child.getTotalDuration()) {
-                    // Re-enter when the playhead is inside the child's range after
-                    // scrubbing back.
-                    child.start(entry.offset);
+                    // On scrub-back, eagerly re-enter children past the playhead
+                    // so they snap to their start values. On forward playback
+                    // only re-enter when the playhead has reached the child.
+                    if (scrubbingBack || effectiveLocal >= entry.offset) {
+                        child.start(entry.offset);
+                    }
+                }
+                // On scrub-back, clamp late children to their offset so they
+                // output start values. On forward playback let the child
+                // start lazily (no output until playhead reaches offset).
+                if (scrubbingBack && effectiveLocal < entry.offset) {
+                    child.update(entry.offset);
+                }
+                else if (!scrubbingBack && effectiveLocal < entry.offset && !child.isPlaying()) ;
+                else {
+                    child.update(effectiveLocal);
                 }
-                // Clamp the lower end so reversed/scrubbed playheads snap the
-                // child to its start value instead of freezing on stale values.
-                child.update(effectiveLocal < entry.offset ? entry.offset : effectiveLocal);
             }
             if (!isFinite(this._duration)) {
                 if (this._onUpdateCallback)
@@ -1539,6 +1559,10 @@ define(['exports'], (function (exports) { 'use strict';
             if (this._duration === 0 || time >= this._startTime + this._duration) {
                 if (this._onCompleteCallback)
                     this._onCompleteCallback(this);
+                // Store the ideal next-cycle boundary so start() snaps to it
+                // instead of the overshooting wall-clock time. This keeps
+                // repeated timelines precisely aligned with longer ones.
+                this._nextStartTime = this._startTime + this._duration;
                 this._isPlaying = false;
                 return false;
             }

dist/tween.cjs

@@ -580,9 +580,7 @@ var Tween = /** @class */ (function () {
                     temp.push(value);
                 }
                 if (isInterpolationList) {
-                    // if (_valuesStart[property] === undefined) { // handle end values only the first time. NOT NEEDED? setupProperties is now guarded by _propertiesAreSetUp.
                     _valuesEnd[property] = temp;
-                    // }
                 }
             }
             // handle the deepness of the values
@@ -1045,6 +1043,7 @@ var Timeline = /** @class */ (function () {
         this._isPlaying = false;
         this._isPaused = false;
         this._pauseStart = 0;
+        this._lastUpdateTime = -Infinity;
         this._onStartCallbackFired = false;
         // Empty on purpose. Use `.add()` to compose.
         // Sequential by default, parallel via explicit offsets, labels, or options.
@@ -1425,7 +1424,13 @@ var Timeline = /** @class */ (function () {
         this._isPlaying = true;
         this._isPaused = false;
         this._onStartCallbackFired = false;
-        this._startTime = time;
+        // Snap to the ideal cycle boundary when restarting a finished
+        // timeline, so repeated timelines stay in sync with longer ones.
+        // Only when the caller's time is at or past the boundary;
+        // a time before the boundary means a deliberate scrub-back.
+        this._startTime = this._nextStartTime !== undefined && time >= this._nextStartTime ? this._nextStartTime : time;
+        this._nextStartTime = undefined;
+        this._lastUpdateTime = -Infinity;
         for (var _i = 0, _a = this._entries; _i < _a.length; _i++) {
             var entry = _a[_i];
             if (entry.node.isPlaying())
@@ -1509,26 +1514,41 @@ var Timeline = /** @class */ (function () {
         }
         var timelineLocal = time - this._startTime;
         var effectiveLocal = Math.min(timelineLocal, this._duration);
+        // Detect scrub-back vs forward play: only eagerly restart/clamp
+        // late-offset children when the playhead moved backward. On
+        // forward playback (including auto-restart), children start
+        // lazily so same-property tweens chain correctly.
+        var scrubbingBack = time < this._lastUpdateTime;
+        this._lastUpdateTime = time;
         for (var _i = 0, _a = this._entries; _i < _a.length; _i++) {
             var entry = _a[_i];
             var child = entry.node;
             if (!entry.started) {
-                // First start must wait until due; a never-started child left
-                // behind stays untouched. (Later re-starts are harmless and
-                // handled below, since Tween keeps its captured setup.)
+                // First start must wait until due; a never-started child
+                // left behind stays untouched.
                 if (effectiveLocal < entry.offset)
                     continue;
                 child.start(entry.offset);
                 entry.started = true;
             }
             else if (!child.isPlaying() && effectiveLocal < entry.offset + child.getTotalDuration()) {
-                // Re-enter when the playhead is inside the child's range after
-                // scrubbing back.
-                child.start(entry.offset);
+                // On scrub-back, eagerly re-enter children past the playhead
+                // so they snap to their start values. On forward playback
+                // only re-enter when the playhead has reached the child.
+                if (scrubbingBack || effectiveLocal >= entry.offset) {
+                    child.start(entry.offset);
+                }
+            }
+            // On scrub-back, clamp late children to their offset so they
+            // output start values. On forward playback let the child
+            // start lazily (no output until playhead reaches offset).
+            if (scrubbingBack && effectiveLocal < entry.offset) {
+                child.update(entry.offset);
+            }
+            else if (!scrubbingBack && effectiveLocal < entry.offset && !child.isPlaying()) ;
+            else {
+                child.update(effectiveLocal);
             }
-            // Clamp the lower end so reversed/scrubbed playheads snap the
-            // child to its start value instead of freezing on stale values.
-            child.update(effectiveLocal < entry.offset ? entry.offset : effectiveLocal);
         }
         if (!isFinite(this._duration)) {
             if (this._onUpdateCallback)
@@ -1541,6 +1561,10 @@ var Timeline = /** @class */ (function () {
         if (this._duration === 0 || time >= this._startTime + this._duration) {
             if (this._onCompleteCallback)
                 this._onCompleteCallback(this);
+            // Store the ideal next-cycle boundary so start() snaps to it
+            // instead of the overshooting wall-clock time. This keeps
+            // repeated timelines precisely aligned with longer ones.
+            this._nextStartTime = this._startTime + this._duration;
             this._isPlaying = false;
             return false;
         }

dist/tween.d.ts

@@ -303,6 +303,8 @@ declare class Timeline {
     private _isPlaying;
     private _isPaused;
     private _pauseStart;
+    private _nextStartTime;
+    private _lastUpdateTime;
     private _onStartCallback?;
     private _onStartCallbackFired;
     private _onUpdateCallback?;