[feature] Extend Timeline with sync, call(), and alternate loop support

[Karanjot786]

What to build

Extend the Timeline class in @termuijs/motion with three new capabilities. sync(subTimeline, offsetMs) locks a sub-timeline at a given millisecond offset. call(fn, atMs) fires a callback at an exact millisecond mark. alternate: true in loop options plays the timeline forward then backward in a ping-pong pattern. The timeline auto-requests live mode when playing and drops it on completion.

Acceptance criteria

• Synced timelines start at the correct offset
• call(fn, 500) fires at 500ms
• Alternate loop reverses direction after the first pass
• Live mode is auto-managed
• Tests use createVirtualClock from the testing package

Implementation notes

• Edit packages/motion/src/timeline.ts
• Edit packages/motion/src/timeline.test.ts
• Look at packages/motion/src/ for patterns

Example usage

import { Timeline } from '@termuijs/motion';

const tl = new Timeline({ loop: true, alternate: true });

tl.add(box, { x: [0, 100] }, { duration: 500 });
tl.call(() => console.log('halfway'), 250);

const sub = new Timeline();
sub.add(label, { opacity: [0, 1] }, { duration: 200 });
tl.sync(sub, 100); // sub starts at 100ms into tl

tl.play();

GSSoC 2026

This is an intermediate-level issue. Comment "I would like to work on this" to get assigned. You have 7 days to open a PR after assignment.

Read CONTRIBUTING.md before starting.

[NachiketPatil26]

I'd like to take this on under GSSoC 2026, but I want to flag a scope question before claiming it.

The issue title says "extend Timeline," but I can't find a Timeline class anywhere in packages/motion/ (or any other package). The motion package currently ships spring, transitions, and timer-pool, with no timeline.ts. Acceptance criterion #5 also references createVirtualClock from the testing package, which I can't locate either.

So this PR would actually be:

1. Designing and implementing a full Timeline class (add, play, pause, seek, plus the three new features: sync, call, alternate).
2. Adding a createVirtualClock helper to @termuijs/testing.
3. Wiring Timeline into the existing timer-pool / live-mode plumbing.
4. Writing the test suite.

That's well beyond a +35-pt extension — it's a foundational animation primitive, and I don't want to make all of those API decisions unilaterally. Could you confirm one of:

(a) Yes, build the whole thing — happy with my judgment on the API shape.
(b) There's a Timeline branch/PR somewhere I'm missing, point me at it.
(c) Scope down — just land createVirtualClock and a minimal Timeline skeleton; sync/call/alternate become follow-ups.

Happy to start as soon as I know which direction. Thanks!

[jagnyaseni-panda]

Hi @Karanjot786 ,

I noticed that this issue is already assigned. If it becomes available, could you please consider assigning it to me?

I would be happy to work on it as part of GSSoC 2026.

Thank you !

[aanyacloud]

I would like to work on this

[github-actions]

Hi @aanyacloud. You already have 2 open issues assigned: #476, #144.

Open and merge a PR from one of those first. Then comment here again to claim this one.

This keeps work moving and gives every contributor a fair chance.

[abhijnyan-codes]

I would like to work on this

[github-actions]

Hi @abhijnyan-codes. @NachiketPatil26 already claimed this issue. The bot frees it automatically if they do not open a PR within 7 days.

[Karanjot786]

The Timeline widget in packages/widgets/src/display/Timeline.ts is a static status-list display (step indicators with done/active/pending icons). The animation-timeline you need lives in packages/motion/ — look at packages/motion/src/sequence.ts as the closest existing primitive for ordered time-based callbacks. Implement sync(subTimeline, offsetMs) to pin a child timeline at a given millisecond offset, call(fn, atMs) to fire a callback at an exact mark, and an alternate flag in loop options to reverse direction after the first pass (ping-pong). Wire live-mode auto-request around play/stop.