feat: drive timeline timing with a virtual clock instead of real timers

[johngeorgewright]

Why

Timing relied on wall-clock setTimeout — 1ms per dash, Tn ms per timer. That made the timeline slow, machine-dependent, and prone to drift between two timelines that are meant to line up frame-for-frame. The whole point of marble/timeline testing is deterministic timing, so the real-timer dependency was the core flaw.

What

Replace wall-clock timing with a deterministic virtual Clock measured in frames:

• Clock (default impl) + Clockable interface — a frame counter with now, wait(frames), and advance(frames?). No setTimeout, no Date.now().
• Injected, default-fresh — Timeline.create(str, { clock }). Omit it and each timeline gets its own; pass the same instance to advance two timelines in lockstep so their timers line up on every run.
• Threaded through parsing — the clock flows Timeline → parse(timeline, { clock }) → each item constructor via TimelineItemOptions.
• TimelineTimer now derives finished/timeLeft from clock.now and gets its promise from clock.wait(ms).
• Docs — new "Consistent timing" section, plus a "Driving real timers" example showing a Clockable adapter over @sinonjs/fake-timers so a timeline shares one clock with the real setInterval/setTimeout in code under test.

Tests

tsc --noEmit clean, build clean, bun test → 7 pass (originals + new coverage for frame advancement, deterministic timer completion, shared-clock identity, and the Clockable injection seam).

Breaking changes

TimelineParsable.parse and TimelineItem constructors now take a TimelineItemOptions argument. Custom parsers should forward options to super/the item constructor to share the timeline's clock. TimelineTimer is backed by a Clockable rather than real wall-clock time.

🤖 Generated with Claude Code